Brunobkr/llama.cpp_AlgMor24_github

1# [![unified][logo]][site]2 3[![Build][build-badge]][build]4[![Coverage][coverage-badge]][coverage]5[![Downloads][downloads-badge]][downloads]6[![Size][size-badge]][size]7[![Sponsors][sponsors-badge]][collective]8[![Backers][backers-badge]][collective]9[![Chat][chat-badge]][chat]10 11**unified** lets you inspect and transform content with plugins.12 13## Contents14 15* [What is this?](#what-is-this)16* [When should I use this?](#when-should-i-use-this)17* [Install](#install)18* [Use](#use)19* [Overview](#overview)20* [API](#api)21  * [`processor()`](#processor)22  * [`processor.compiler`](#processorcompiler)23  * [`processor.data([key[, value]])`](#processordatakey-value)24  * [`processor.freeze()`](#processorfreeze)25  * [`processor.parse(file)`](#processorparsefile)26  * [`processor.parser`](#processorparser)27  * [`processor.process(file[, done])`](#processorprocessfile-done)28  * [`processor.processSync(file)`](#processorprocesssyncfile)29  * [`processor.run(tree[, file][, done])`](#processorruntree-file-done)30  * [`processor.runSync(tree[, file])`](#processorrunsynctree-file)31  * [`processor.stringify(tree[, file])`](#processorstringifytree-file)32  * [`processor.use(plugin[, options])`](#processoruseplugin-options)33  * [`CompileResultMap`](#compileresultmap)34  * [`CompileResults`](#compileresults)35  * [`Compiler`](#compiler)36  * [`Data`](#data)37  * [`Parser`](#parser)38  * [`Pluggable`](#pluggable)39  * [`PluggableList`](#pluggablelist)40  * [`Plugin`](#plugin)41  * [`PluginTuple`](#plugintuple)42  * [`Preset`](#preset)43  * [`ProcessCallback`](#processcallback)44  * [`Processor`](#processor-1)45  * [`RunCallback`](#runcallback)46  * [`Settings`](#settings)47  * [`TransformCallback`](#transformcallback)48  * [`Transformer`](#transformer)49* [Types](#types)50* [Compatibility](#compatibility)51* [Contribute](#contribute)52* [Sponsor](#sponsor)53* [Acknowledgments](#acknowledgments)54* [License](#license)55 56## What is this?57 58unified is two things:59 60* **unified** is a collective of 500+ free and open source packages that work61  with content as structured data (ASTs)62* `unified` (this project) is the core package, used in 1.3m+ projects on GH,63  to process content with plugins64 65Several ecosystems are built on unified around different kinds of content.66Notably, [remark][] (markdown), [rehype][] (HTML), and [retext][] (natural67language).68These ecosystems can be connected together.69 70* for more about us, see [`unifiedjs.com`][site]71* for updates, see [@unifiedjs][twitter] on Twitter72* for questions, see [support][]73* to help, see [contribute][] and [sponsor][] below74 75## When should I use this?76 77In some cases, you are already using unified.78For example, it’s used in MDX, Gatsby, Docusaurus, etc.79In those cases, you don’t need to add `unified` yourself but you can include80plugins into those projects.81 82But the real fun (for some) is to get your hands dirty and work with syntax83trees and build with it yourself.84You can create those projects, or things like Prettier, or your own site85generator.86You can connect utilities together and make your own plugins that check for87problems and transform from one thing to another.88 89When you are dealing with one type of content (such as markdown), you can use90the main package of that ecosystem instead (so `remark`).91When you are dealing with different kinds of content (such as markdown and92HTML), it’s recommended to use `unified` itself, and pick and choose the plugins93you need.94 95## Install96 97This package is [ESM only][esm].98In Node.js (version 16+), install with [npm][]:99 100```sh101npm install unified102```103 104In Deno with [`esm.sh`][esmsh]:105 106```js107import {unified} from 'https://esm.sh/unified@11'108```109 110In browsers with [`esm.sh`][esmsh]:111 112```html113<script type="module">114  import {unified} from 'https://esm.sh/unified@11?bundle'115</script>116```117 118## Use119 120```js121import rehypeDocument from 'rehype-document'122import rehypeFormat from 'rehype-format'123import rehypeStringify from 'rehype-stringify'124import remarkParse from 'remark-parse'125import remarkRehype from 'remark-rehype'126import {unified} from 'unified'127import {reporter} from 'vfile-reporter'128 129const file = await unified()130  .use(remarkParse)131  .use(remarkRehype)132  .use(rehypeDocument, {title: '👋🌍'})133  .use(rehypeFormat)134  .use(rehypeStringify)135  .process('# Hello world!')136 137console.error(reporter(file))138console.log(String(file))139```140 141Yields:142 143```txt144no issues found145```146 147```html148<!doctype html>149<html lang="en">150  <head>151    <meta charset="utf-8">152    <title>👋🌍</title>153    <meta name="viewport" content="width=device-width, initial-scale=1">154  </head>155  <body>156    <h1>Hello world!</h1>157  </body>158</html>159```160 161<!-- Old name: -->162 163<a name="description"></a>164 165## Overview166 167`unified` is an interface for processing content with syntax trees.168Syntax trees are a representation of content understandable to programs.169Those programs, called *[plugins][api-plugin]*, take these trees and inspect and170modify them.171To get to the syntax tree from text, there is a *[parser][api-parser]*.172To get from that back to text, there is a *[compiler][api-compiler]*.173This is the *[process][api-process]* of a *processor*.174 175```ascii176| ........................ process ........................... |177| .......... parse ... | ... run ... | ... stringify ..........|178 179          +--------+                     +----------+180Input ->- | Parser | ->- Syntax Tree ->- | Compiler | ->- Output181          +--------+          |          +----------+182                              X183                              |184                       +--------------+185                       | Transformers |186                       +--------------+187```188 189###### Processors190 191Processors process content.192On its own, `unified` (the root processor) doesn’t work.193It needs to be configured with plugins to work.194For example:195 196```js197const processor = unified()198  .use(remarkParse)199  .use(remarkRehype)200  .use(rehypeDocument, {title: '👋🌍'})201  .use(rehypeFormat)202  .use(rehypeStringify)203```204 205That processor can do different things.206It can:207 208* …parse markdown (`parse`)209* …turn parsed markdown into HTML and format the HTML (`run`)210* …compile HTML (`stringify`)211* …do all of the above (`process`)212 213Every processor implements another processor.214To create a processor, call another processor.215The new processor is configured to work the same as its ancestor.216But when the descendant processor is configured in the future it does not affect217the ancestral processor.218 219When processors are exposed from a module (for example, `unified` itself) they220should not be configured directly, as that would change their behavior for all221module users.222Those processors are *[frozen][api-freeze]* and they should be called to create223a new processor before they are used.224 225###### File226 227When processing a document, metadata is gathered about that document.228[`vfile`][vfile] is the file format that stores data, metadata, and messages229about files for unified and plugins.230 231There are several [utilities][vfile-utilities] for working with these files.232 233###### Syntax tree234 235The syntax trees used in unified are [unist][] nodes.236A tree represents a whole document and each [node][] is a plain JavaScript237object with a `type` field.238The semantics of nodes and the format of syntax trees is defined by other239projects:240 241* [esast][] — JavaScript242* [hast][] — HTML243* [mdast][] — markdown244* [nlcst][] — natural language245* [xast][] — XML246 247There are many utilities for working with trees listed in each aforementioned248project and maintained in the [`syntax-tree`][syntax-tree] organization.249These utilities are a level lower than unified itself and are building blocks250that can be used to make plugins.251 252<!-- Old name: -->253 254<a name="list-of-processors"></a>255 256###### Ecosystems257 258Around each syntax tree is an ecosystem that focusses on that particular kind259of content.260At their core, they parse text to a tree and compile that tree back to text.261They also provide plugins that work with the syntax tree, without requiring262that the end user has knowledge about that tree.263 264* [rehype][] (hast) — HTML265* [remark][] (mdast) — markdown266* [retext][] (nlcst) — natural language267 268<a name="list-of-plugins"></a>269 270###### Plugins271 272Each aforementioned ecosystem comes with a large set of plugins that you can273pick and choose from to do all kinds of things.274 275* [List of remark plugins][remark-plugins] ·276  [`remarkjs/awesome-remark`][awesome-remark] ·277  [`remark-plugin` topic][topic-remark-plugin]278* [List of rehype plugins][rehype-plugins] ·279  [`rehypejs/awesome-rehype`][awesome-rehype] ·280  [`rehype-plugin` topic][topic-rehype-plugin]281* [List of retext plugins][retext-plugins] ·282  [`retextjs/awesome-retext`][awesome-retext] ·283  [`retext-plugin` topic][topic-retext-plugin]284 285There are also a few plugins that work in any ecosystem:286 287* [`unified-diff`](https://github.com/unifiedjs/unified-diff)288  — ignore unrelated messages in GitHub Actions and Travis289* [`unified-infer-git-meta`](https://github.com/unifiedjs/unified-infer-git-meta)290  — infer metadata of a document from Git291* [`unified-message-control`](https://github.com/unifiedjs/unified-message-control)292  — enable, disable, and ignore messages from content293 294###### Configuration295 296Processors are configured with [plugins][api-plugin] or with the297[`data`][api-data] method.298Most plugins also accept configuration through options.299See each plugin’s readme for more info.300 301###### Integrations302 303unified can integrate with the file system through304[`unified-engine`][unified-engine].305CLI apps can be created with [`unified-args`][unified-args], Gulp plugins with306[`unified-engine-gulp`][unified-engine-gulp], and language servers with307[`unified-language-server`][unified-language-server].308A streaming interface can be created with [`unified-stream`][unified-stream].309 310###### Programming interface311 312The [API][] provided by `unified` allows multiple files to be processed and313gives access to metadata (such as lint messages):314 315```js316import rehypeStringify from 'rehype-stringify'317import remarkParse from 'remark-parse'318import remarkPresetLintMarkdownStyleGuide from 'remark-preset-lint-markdown-style-guide'319import remarkRehype from 'remark-rehype'320import remarkRetext from 'remark-retext'321import retextEnglish from 'retext-english'322import retextEquality from 'retext-equality'323import {unified} from 'unified'324import {reporter} from 'vfile-reporter'325 326const file = await unified()327  .use(remarkParse)328  .use(remarkPresetLintMarkdownStyleGuide)329  .use(remarkRetext, unified().use(retextEnglish).use(retextEquality))330  .use(remarkRehype)331  .use(rehypeStringify)332  .process('*Emphasis* and _stress_, you guys!')333 334console.error(reporter(file))335console.log(String(file))336```337 338Yields:339 340```txt3411:16-1:24 warning Emphasis should use `*` as a marker                                 emphasis-marker remark-lint3421:30-1:34 warning `guys` may be insensitive, use `people`, `persons`, `folks` instead gals-man        retext-equality343 344⚠ 2 warnings345```346 347```html348<p><em>Emphasis</em> and <em>stress</em>, you guys!</p>349```350 351<!-- Old name: -->352 353<a name="processing-between-syntaxes"></a>354 355###### Transforming between ecosystems356 357Ecosystems can be combined in two modes.358 359**Bridge** mode transforms the tree from one format (*origin*) to another360(*destination*).361A different processor runs on the destination tree.362Afterwards, the original processor continues with the origin tree.363 364**Mutate** mode also transforms the syntax tree from one format to another.365But the original processor continues transforming the destination tree.366 367In the previous example (“Programming interface”), `remark-retext` is used in368bridge mode: the origin syntax tree is kept after retext is done; whereas369`remark-rehype` is used in mutate mode: it sets a new syntax tree and discards370the origin tree.371 372The following plugins lets you combine ecosystems:373 374* [`remark-retext`][remark-retext] — turn markdown into natural language375* [`remark-rehype`][remark-rehype] — turn markdown into HTML376* [`rehype-retext`][rehype-retext] — turn HTML into natural language377* [`rehype-remark`][rehype-remark] — turn HTML into markdown378 379## API380 381This package exports the identifier `unified` (the root `processor`).382There is no default export.383 384### `processor()`385 386Create a new processor.387 388###### Returns389 390New *[unfrozen][api-freeze]* processor ([`processor`][api-processor]).391 392This processor is configured to work the same as its ancestor.393When the descendant processor is configured in the future it does not affect394the ancestral processor.395 396###### Example397 398This example shows how a new processor can be created (from `remark`) and linked399to **stdin**(4) and **stdout**(4).400 401```js402import process from 'node:process'403import concatStream from 'concat-stream'404import {remark} from 'remark'405 406process.stdin.pipe(407  concatStream(function (buf) {408    process.stdout.write(String(remark().processSync(buf)))409  })410)411```412 413### `processor.compiler`414 415Compiler to use ([`Compiler`][api-compiler], optional).416 417### `processor.data([key[, value]])`418 419Configure the processor with info available to all plugins.420Information is stored in an object.421 422Typically, options can be given to a specific plugin, but sometimes it makes423sense to have information shared with several plugins.424For example, a list of HTML elements that are self-closing, which is needed425during all [phases][overview].426 427> 👉 **Note**: setting information cannot occur on *[frozen][api-freeze]*428> processors.429> Call the processor first to create a new unfrozen processor.430 431> 👉 **Note**: to register custom data in TypeScript, augment the432> [`Data`][api-data] interface.433 434###### Signatures435 436* `processor = processor.data(key, value)`437* `processor = processor.data(dataset)`438* `value = processor.data(key)`439* `dataset = processor.data()`440 441###### Parameters442 443* `key` ([`keyof Data`][api-data], optional) — field to get444* `value` ([`Data[key]`][api-data]) — value to set445* `values` ([`Data`][api-data]) — values to set446 447###### Returns448 449The current processor when setting ([`processor`][api-processor]), the value at450`key` when getting ([`Data[key]`][api-data]), or the entire dataset when451getting without key ([`Data`][api-data]).452 453###### Example454 455This example show how to get and set info:456 457```js458import {unified} from 'unified'459 460const processor = unified().data('alpha', 'bravo')461 462processor.data('alpha') // => 'bravo'463 464processor.data() // => {alpha: 'bravo'}465 466processor.data({charlie: 'delta'})467 468processor.data() // => {charlie: 'delta'}469```470 471### `processor.freeze()`472 473Freeze a processor.474 475Frozen processors are meant to be extended and not to be configured directly.476 477When a processor is frozen it cannot be unfrozen.478New processors working the same way can be created by calling the processor.479 480It’s possible to freeze processors explicitly by calling `.freeze()`.481Processors freeze automatically when `.parse()`, `.run()`, `.runSync()`,482`.stringify()`, `.process()`, or `.processSync()` are called.483 484###### Returns485 486The current processor ([`processor`][api-processor]).487 488###### Example489 490This example, `index.js`, shows how `rehype` prevents extensions to itself:491 492```js493import rehypeParse from 'rehype-parse'494import rehypeStringify from 'rehype-stringify'495import {unified} from 'unified'496 497export const rehype = unified().use(rehypeParse).use(rehypeStringify).freeze()498```499 500That processor can be used and configured like so:501 502```js503import {rehype} from 'rehype'504import rehypeFormat from 'rehype-format'505// …506 507rehype()508  .use(rehypeFormat)509  // …510```511 512A similar looking example is broken as operates on the frozen interface.513If this behavior was allowed it would result in unexpected behavior so an error514is thrown.515**This is not valid**:516 517```js518import {rehype} from 'rehype'519import rehypeFormat from 'rehype-format'520// …521 522rehype523  .use(rehypeFormat)524  // …525```526 527Yields:528 529```txt530~/node_modules/unified/index.js:426531    throw new Error(532    ^533 534Error: Cannot call `use` on a frozen processor.535Create a new processor first, by calling it: use `processor()` instead of `processor`.536    at assertUnfrozen (~/node_modules/unified/index.js:426:11)537    at Function.use (~/node_modules/unified/index.js:165:5)538    …539```540 541### `processor.parse(file)`542 543Parse text to a syntax tree.544 545> 👉 **Note**: `parse` freezes the processor if not already546> *[frozen][api-freeze]*.547 548> 👉 **Note**: `parse` performs the [parse phase][overview], not the run phase549> or other phases.550 551###### Parameters552 553* `file` ([`Compatible`][vfile-compatible]) — file to parse; typically554  `string` or [`VFile`][vfile]; any value accepted as `x` in `new VFile(x)`555 556###### Returns557 558Syntax tree representing `file` ([`Node`][node]).559 560###### Example561 562This example shows how `parse` can be used to create a tree from a file.563 564```js565import remarkParse from 'remark-parse'566import {unified} from 'unified'567 568const tree = unified().use(remarkParse).parse('# Hello world!')569 570console.log(tree)571```572 573Yields:574 575```js576{577  type: 'root',578  children: [579    {type: 'heading', depth: 1, children: [Array], position: [Object]}580  ],581  position: {582    start: {line: 1, column: 1, offset: 0},583    end: {line: 1, column: 15, offset: 14}584  }585}586```587 588### `processor.parser`589 590Parser to use ([`Parser`][api-parser], optional).591 592### `processor.process(file[, done])`593 594Process the given file as configured on the processor.595 596> 👉 **Note**: `process` freezes the processor if not already597> *[frozen][api-freeze]*.598 599> 👉 **Note**: `process` performs the [parse, run, and stringify600> phases][overview].601 602###### Signatures603 604* `processor.process(file, done)`605* `Promise<VFile> = processor.process(file?)`606 607###### Parameters608 609* `file` ([`Compatible`][vfile-compatible], optional) — file; typically610  `string` or [`VFile`][vfile]; any value accepted as `x` in `new VFile(x)`611* `done` ([`ProcessCallback`][api-process-callback], optional) — callback612 613###### Returns614 615Nothing if `done` is given (`undefined`).616Otherwise a promise, rejected with a fatal error or resolved with the617processed file ([`Promise<VFile>`][vfile]).618 619The parsed, transformed, and compiled value is available at `file.value` (see620note).621 622> 👉 **Note**: unified typically compiles by serializing: most623> compilers return `string` (or `Uint8Array`).624> Some compilers, such as the one configured with625> [`rehype-react`][rehype-react], return other values (in this case, a React626> tree).627> If you’re using a compiler that doesn’t serialize, expect different result628> values.629>630> To register custom results in TypeScript, add them to631> [`CompileResultMap`][api-compile-result-map].632 633###### Example634 635This example shows how `process` can be used to process a file:636 637```js638import rehypeDocument from 'rehype-document'639import rehypeFormat from 'rehype-format'640import rehypeStringify from 'rehype-stringify'641import remarkParse from 'remark-parse'642import remarkRehype from 'remark-rehype'643import {unified} from 'unified'644 645const file = await unified()646  .use(remarkParse)647  .use(remarkRehype)648  .use(rehypeDocument, {title: '👋🌍'})649  .use(rehypeFormat)650  .use(rehypeStringify)651  .process('# Hello world!')652 653console.log(String(file))654```655 656Yields:657 658```html659<!doctype html>660<html lang="en">661  <head>662    <meta charset="utf-8">663    <title>👋🌍</title>664    <meta name="viewport" content="width=device-width, initial-scale=1">665  </head>666  <body>667    <h1>Hello world!</h1>668  </body>669</html>670```671 672### `processor.processSync(file)`673 674Process the given file as configured on the processor.675 676An error is thrown if asynchronous transforms are configured.677 678> 👉 **Note**: `processSync` freezes the processor if not already679> *[frozen][api-freeze]*.680 681> 👉 **Note**: `processSync` performs the [parse, run, and stringify682> phases][overview].683 684###### Parameters685 686* `file` ([`Compatible`][vfile-compatible], optional) — file; typically687  `string` or [`VFile`][vfile]; any value accepted as `x` in `new VFile(x)`688 689###### Returns690 691The processed file ([`VFile`][vfile]).692 693The parsed, transformed, and compiled value is available at `file.value` (see694note).695 696> 👉 **Note**: unified typically compiles by serializing: most697> compilers return `string` (or `Uint8Array`).698> Some compilers, such as the one configured with699> [`rehype-react`][rehype-react], return other values (in this case, a React700> tree).701> If you’re using a compiler that doesn’t serialize, expect different result702> values.703>704> To register custom results in TypeScript, add them to705> [`CompileResultMap`][api-compile-result-map].706 707###### Example708 709This example shows how `processSync` can be used to process a file, if all710transformers are synchronous.711 712```js713import rehypeDocument from 'rehype-document'714import rehypeFormat from 'rehype-format'715import rehypeStringify from 'rehype-stringify'716import remarkParse from 'remark-parse'717import remarkRehype from 'remark-rehype'718import {unified} from 'unified'719 720const processor = unified()721  .use(remarkParse)722  .use(remarkRehype)723  .use(rehypeDocument, {title: '👋🌍'})724  .use(rehypeFormat)725  .use(rehypeStringify)726 727console.log(String(processor.processSync('# Hello world!')))728```729 730Yields:731 732```html733<!doctype html>734<html lang="en">735  <head>736    <meta charset="utf-8">737    <title>👋🌍</title>738    <meta name="viewport" content="width=device-width, initial-scale=1">739  </head>740  <body>741    <h1>Hello world!</h1>742  </body>743</html>744```745 746### `processor.run(tree[, file][, done])`747 748Run *[transformers][api-transformer]* on a syntax tree.749 750> 👉 **Note**: `run` freezes the processor if not already751> *[frozen][api-freeze]*.752 753> 👉 **Note**: `run` performs the [run phase][overview], not other phases.754 755###### Signatures756 757* `processor.run(tree, done)`758* `processor.run(tree, file, done)`759* `Promise<Node> = processor.run(tree, file?)`760 761###### Parameters762 763* `tree` ([`Node`][node]) — tree to transform and inspect764* `file` ([`Compatible`][vfile-compatible], optional) — file associated765  with `node`; any value accepted as `x` in `new VFile(x)`766* `done` ([`RunCallback`][api-run-callback], optional) — callback767 768###### Returns769 770Nothing if `done` is given (`undefined`).771Otherwise, a promise rejected with a fatal error or resolved with the772transformed tree ([`Promise<Node>`][node]).773 774###### Example775 776This example shows how `run` can be used to transform a tree:777 778```js779import remarkReferenceLinks from 'remark-reference-links'780import {unified} from 'unified'781import {u} from 'unist-builder'782 783const tree = u('root', [784  u('paragraph', [785    u('link', {href: 'https://example.com'}, [u('text', 'Example Domain')])786  ])787])788 789const changedTree = await unified().use(remarkReferenceLinks).run(tree)790 791console.log(changedTree)792```793 794Yields:795 796```js797{798  type: 'root',799  children: [800    {type: 'paragraph', children: [Array]},801    {type: 'definition', identifier: '1', title: '', url: undefined}802  ]803}804```805 806### `processor.runSync(tree[, file])`807 808Run *[transformers][api-transformer]* on a syntax tree.809 810An error is thrown if asynchronous transforms are configured.811 812> 👉 **Note**: `runSync` freezes the processor if not already813> *[frozen][api-freeze]*.814 815> 👉 **Note**: `runSync` performs the [run phase][overview], not other phases.816 817###### Parameters818 819* `tree` ([`Node`][node]) — tree to transform and inspect820* `file` ([`Compatible`][vfile-compatible], optional) — file associated821  with `node`; any value accepted as `x` in `new VFile(x)`822 823###### Returns824 825Transformed tree ([`Node`][node]).826 827### `processor.stringify(tree[, file])`828 829Compile a syntax tree.830 831> 👉 **Note**: `stringify` freezes the processor if not already832> *[frozen][api-freeze]*.833 834> 👉 **Note**: `stringify` performs the [stringify phase][overview], not the run835> phase or other phases.836 837###### Parameters838 839* `tree` ([`Node`][node]) — tree to compile840* `file` ([`Compatible`][vfile-compatible], optional) — file associated841  with `node`; any value accepted as `x` in `new VFile(x)`842 843###### Returns844 845Textual representation of the tree (`Uint8Array` or `string`, see note).846 847> 👉 **Note**: unified typically compiles by serializing: most compilers848> return `string` (or `Uint8Array`).849> Some compilers, such as the one configured with850> [`rehype-react`][rehype-react], return other values (in this case, a851> React tree).852> If you’re using a compiler that doesn’t serialize, expect different853> result values.854>855> To register custom results in TypeScript, add them to856> [`CompileResultMap`][api-compile-result-map].857 858###### Example859 860This example shows how `stringify` can be used to serialize a syntax tree:861 862```js863import {h} from 'hastscript'864import rehypeStringify from 'rehype-stringify'865import {unified} from 'unified'866 867const tree = h('h1', 'Hello world!')868 869const document = unified().use(rehypeStringify).stringify(tree)870 871console.log(document)872```873 874Yields:875 876```html877<h1>Hello world!</h1>878```879 880### `processor.use(plugin[, options])`881 882Configure the processor to use a plugin, a list of usable values, or a preset.883 884If the processor is already using a plugin, the previous plugin configuration885is changed based on the options that are passed in.886In other words, the plugin is not added a second time.887 888> 👉 **Note**: `use` cannot be called on [*frozen*][api-freeze] processors.889> Call the processor first to create a new unfrozen processor.890 891###### Signatures892 893* `processor.use(preset?)`894* `processor.use(list)`895* `processor.use(plugin[, ...parameters])`896 897###### Parameters898 899* `preset` ([`Preset`][api-preset]) — plugins and settings900* `list` ([`PluggableList`][api-pluggable-list]) — list of usable things901* `plugin` ([`Plugin`][api-plugin]) — plugin902* `parameters` (`Array<unknown>`) — configuration for `plugin`, typically a903  single options object904 905###### Returns906 907Current processor ([`processor`][api-processor]).908 909###### Example910 911There are many ways to pass plugins to `.use()`.912This example gives an overview:913 914```js915import {unified} from 'unified'916 917unified()918  // Plugin with options:919  .use(pluginA, {x: true, y: true})920  // Passing the same plugin again merges configuration (to `{x: true, y: false, z: true}`):921  .use(pluginA, {y: false, z: true})922  // Plugins:923  .use([pluginB, pluginC])924  // Two plugins, the second with options:925  .use([pluginD, [pluginE, {}]])926  // Preset with plugins and settings:927  .use({plugins: [pluginF, [pluginG, {}]], settings: {position: false}})928  // Settings only:929  .use({settings: {position: false}})930```931 932### `CompileResultMap`933 934Interface of known results from compilers (TypeScript type).935 936Normally, compilers result in text ([`Value`][vfile-value] of `vfile`).937When you compile to something else, such as a React node (as in,938`rehype-react`), you can augment this interface to include that type.939 940```ts941import type {ReactNode} from 'somewhere'942 943declare module 'unified' {944  interface CompileResultMap {945    // Register a new result (value is used, key should match it).946    ReactNode: ReactNode947  }948}949 950export {} // You may not need this, but it makes sure the file is a module.951```952 953Use [`CompileResults`][api-compile-results] to access the values.954 955###### Type956 957```ts958interface CompileResultMap {959  // Note: if `Value` from `VFile` is changed, this should too.960  Uint8Array: Uint8Array961  string: string962}963```964 965### `CompileResults`966 967Acceptable results from compilers (TypeScript type).968 969To register custom results, add them to970[`CompileResultMap`][api-compile-result-map].971 972###### Type973 974```ts975type CompileResults = CompileResultMap[keyof CompileResultMap]976```977 978### `Compiler`979 980A **compiler** handles the compiling of a syntax tree to something else981(in most cases, text) (TypeScript type).982 983It is used in the stringify phase and called with a [`Node`][node]984and [`VFile`][vfile] representation of the document to compile.985It should return the textual representation of the given tree (typically986`string`).987 988> 👉 **Note**: unified typically compiles by serializing: most compilers989> return `string` (or `Uint8Array`).990> Some compilers, such as the one configured with991> [`rehype-react`][rehype-react], return other values (in this case, a992> React tree).993> If you’re using a compiler that doesn’t serialize, expect different994> result values.995>996> To register custom results in TypeScript, add them to997> [`CompileResultMap`][api-compile-result-map].998 999###### Type1000 1001```ts1002type Compiler<1003  Tree extends Node = Node,1004  Result extends CompileResults = CompileResults1005> = (tree: Tree, file: VFile) => Result1006```1007 1008### `Data`1009 1010Interface of known data that can be supported by all plugins (TypeScript type).1011 1012Typically, options can be given to a specific plugin, but sometimes it makes1013sense to have information shared with several plugins.1014For example, a list of HTML elements that are self-closing, which is needed1015during all phases.1016 1017To type this, do something like:1018 1019```ts1020declare module 'unified' {1021  interface Data {1022    htmlVoidElements?: Array<string> | undefined1023  }1024}1025 1026export {} // You may not need this, but it makes sure the file is a module.1027```1028 1029###### Type1030 1031```ts1032interface Data {1033  settings?: Settings | undefined1034}1035```1036 1037See [`Settings`][api-settings] for more info.1038 1039### `Parser`1040 1041A **parser** handles the parsing of text to a syntax tree (TypeScript type).1042 1043It is used in the parse phase and is called with a `string` and1044[`VFile`][vfile] of the document to parse.1045It must return the syntax tree representation of the given file1046([`Node`][node]).1047 1048###### Type1049 1050```ts1051type Parser<Tree extends Node = Node> = (document: string, file: VFile) => Tree1052```1053 1054### `Pluggable`1055 1056Union of the different ways to add plugins and settings (TypeScript type).1057 1058###### Type1059 1060```ts1061type Pluggable =1062  | Plugin<Array<any>, any, any>1063  | PluginTuple<Array<any>, any, any>1064  | Preset1065```1066 1067See [`Plugin`][api-plugin], [`PluginTuple`][api-plugin-tuple],1068and [`Preset`][api-preset] for more info.1069 1070### `PluggableList`1071 1072List of plugins and presets (TypeScript type).1073 1074###### Type1075 1076```ts1077type PluggableList = Array<Pluggable>1078```1079 1080See [`Pluggable`][api-pluggable] for more info.1081 1082### `Plugin`1083 1084Single plugin (TypeScript type).1085 1086Plugins configure the processors they are applied on in the following ways:1087 1088* they change the processor, such as the parser, the compiler, or by1089  configuring data1090* they specify how to handle trees and files1091 1092In practice, they are functions that can receive options and configure the1093processor (`this`).1094 1095> 👉 **Note**: plugins are called when the processor is *frozen*, not when they1096> are applied.1097 1098###### Type1099 1100```ts1101type Plugin<1102  PluginParameters extends unknown[] = [],1103  Input extends Node | string | undefined = Node,1104  Output = Input1105> = (1106  this: Processor,1107  ...parameters: PluginParameters1108) => Input extends string // Parser.1109  ? Output extends Node | undefined1110    ? undefined | void1111    : never1112  : Output extends CompileResults // Compiler.1113  ? Input extends Node | undefined1114    ? undefined | void1115    : never1116  : // Inspect/transform.1117      | Transformer<1118          Input extends Node ? Input : Node,1119          Output extends Node ? Output : Node1120        >1121      | undefined1122      | void1123```1124 1125See [`Transformer`][api-transformer] for more info.1126 1127###### Example1128 1129`move.js`:1130 1131```js1132/**1133 * @typedef Options1134 *   Configuration (required).1135 * @property {string} extname1136 *   File extension to use (must start with `.`).1137 */1138 1139/** @type {import('unified').Plugin<[Options]>} */1140export function move(options) {1141  if (!options || !options.extname) {1142    throw new Error('Missing `options.extname`')1143  }1144 1145  return function (_, file) {1146    if (file.extname && file.extname !== options.extname) {1147      file.extname = options.extname1148    }1149  }1150}1151```1152 1153`example.md`:1154 1155```markdown1156# Hello, world!1157```1158 1159`example.js`:1160 1161```js1162import rehypeStringify from 'rehype-stringify'1163import remarkParse from 'remark-parse'1164import remarkRehype from 'remark-rehype'1165import {read, write} from 'to-vfile'1166import {unified} from 'unified'1167import {reporter} from 'vfile-reporter'1168import {move} from './move.js'1169 1170const file = await unified()1171  .use(remarkParse)1172  .use(remarkRehype)1173  .use(move, {extname: '.html'})1174  .use(rehypeStringify)1175  .process(await read('example.md'))1176 1177console.error(reporter(file))1178await write(file) // Written to `example.html`.1179```1180 1181Yields:1182 1183```txt1184example.md: no issues found1185```1186 1187…and in `example.html`:1188 1189```html1190<h1>Hello, world!</h1>1191```1192 1193### `PluginTuple`1194 1195Tuple of a plugin and its configuration (TypeScript type).1196 1197The first item is a plugin, the rest are its parameters.1198 1199###### Type1200 

Showing the first 1,200 of 1836 lines. Download the file for the rest.