AK-21/Graphite-Industrial-Intelligence

1# parse-entities2 3[![Build][build-badge]][build]4[![Coverage][coverage-badge]][coverage]5[![Downloads][downloads-badge]][downloads]6[![Size][size-badge]][size]7 8Parse HTML character references.9 10## Contents11 12* [What is this?](#what-is-this)13* [When should I use this?](#when-should-i-use-this)14* [Install](#install)15* [Use](#use)16* [API](#api)17  * [`parseEntities(value[, options])`](#parseentitiesvalue-options)18* [Types](#types)19* [Compatibility](#compatibility)20* [Security](#security)21* [Related](#related)22* [Contribute](#contribute)23* [License](#license)24 25## What is this?26 27This is a small and powerful decoder of HTML character references (often called28entities).29 30## When should I use this?31 32You can use this for spec-compliant decoding of character references.33It’s small and fast enough to do that well.34You can also use this when making a linter, because there are different warnings35emitted with reasons for why and positional info on where they happened.36 37## Install38 39This package is [ESM only][esm].40In Node.js (version 14.14+, 16.0+), install with [npm][]:41 42```sh43npm install parse-entities44```45 46In Deno with [`esm.sh`][esmsh]:47 48```js49import {parseEntities} from 'https://esm.sh/parse-entities@3'50```51 52In browsers with [`esm.sh`][esmsh]:53 54```html55<script type="module">56  import {parseEntities} from 'https://esm.sh/parse-entities@3?bundle'57</script>58```59 60## Use61 62```js63import {parseEntities} from 'parse-entities'64 65console.log(parseEntities('alpha &amp bravo')))66// => alpha & bravo67 68console.log(parseEntities('charlie &copycat; delta'))69// => charlie ©cat; delta70 71console.log(parseEntities('echo &copy; foxtrot &#8800; golf &#x1D306; hotel'))72// => echo © foxtrot ≠ golf 𝌆 hotel73```74 75## API76 77This package exports the identifier `parseEntities`.78There is no default export.79 80### `parseEntities(value[, options])`81 82Parse HTML character references.83 84##### `options`85 86Configuration (optional).87 88###### `options.additional`89 90Additional character to accept (`string?`, default: `''`).91This allows other characters, without error, when following an ampersand.92 93###### `options.attribute`94 95Whether to parse `value` as an attribute value (`boolean?`, default: `false`).96This results in slightly different behavior.97 98###### `options.nonTerminated`99 100Whether to allow nonterminated references (`boolean`, default: `true`).101For example, `&copycat` for `©cat`.102This behavior is compliant to the spec but can lead to unexpected results.103 104###### `options.position`105 106Starting `position` of `value` (`Position` or `Point`, optional).107Useful when dealing with values nested in some sort of syntax tree.108The default is:109 110```js111{line: 1, column: 1, offset: 0}112```113 114###### `options.warning`115 116Error handler ([`Function?`][warning]).117 118###### `options.text`119 120Text handler ([`Function?`][text]).121 122###### `options.reference`123 124Reference handler ([`Function?`][reference]).125 126###### `options.warningContext`127 128Context used when calling `warning` (`'*'`, optional).129 130###### `options.textContext`131 132Context used when calling `text` (`'*'`, optional).133 134###### `options.referenceContext`135 136Context used when calling `reference` (`'*'`, optional)137 138##### Returns139 140`string` — decoded `value`.141 142#### `function warning(reason, point, code)`143 144Error handler.145 146###### Parameters147 148* `this` (`*`) — refers to `warningContext` when given to `parseEntities`149* `reason` (`string`) — human readable reason for emitting a parse error150* `point` ([`Point`][point]) — place where the error occurred151* `code` (`number`) — machine readable code the error152 153The following codes are used:154 155| Code | Example            | Note                                          |156| ---- | ------------------ | --------------------------------------------- |157| `1`  | `foo &amp bar`     | Missing semicolon (named)                     |158| `2`  | `foo &#123 bar`    | Missing semicolon (numeric)                   |159| `3`  | `Foo &bar baz`     | Empty (named)                                 |160| `4`  | `Foo &#`           | Empty (numeric)                               |161| `5`  | `Foo &bar; baz`    | Unknown (named)                               |162| `6`  | `Foo &#128; baz`   | [Disallowed reference][invalid]               |163| `7`  | `Foo &#xD800; baz` | Prohibited: outside permissible unicode range |164 165#### `function text(value, position)`166 167Text handler.168 169###### Parameters170 171* `this` (`*`) — refers to `textContext` when given to `parseEntities`172* `value` (`string`) — string of content173* `position` ([`Position`][position]) — place where `value` starts and ends174 175#### `function reference(value, position, source)`176 177Character reference handler.178 179###### Parameters180 181* `this` (`*`) — refers to `referenceContext` when given to `parseEntities`182* `value` (`string`) — decoded character reference183* `position` ([`Position`][position]) — place where `source` starts and ends184* `source` (`string`) — raw source of character reference185 186## Types187 188This package is fully typed with [TypeScript][].189It exports the additional types `Options`, `WarningHandler`,190`ReferenceHandler`, and `TextHandler`.191 192## Compatibility193 194This package is at least compatible with all maintained versions of Node.js.195As of now, that is Node.js 14.14+ and 16.0+.196It also works in Deno and modern browsers.197 198## Security199 200This package is safe: it matches the HTML spec to parse character references.201 202## Related203 204* [`wooorm/stringify-entities`](https://github.com/wooorm/stringify-entities)205  — encode HTML character references206* [`wooorm/character-entities`](https://github.com/wooorm/character-entities)207  — info on character references208* [`wooorm/character-entities-html4`](https://github.com/wooorm/character-entities-html4)209  — info on HTML4 character references210* [`wooorm/character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)211  — info on legacy character references212* [`wooorm/character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)213  — info on invalid numeric character references214 215## Contribute216 217Yes please!218See [How to Contribute to Open Source][contribute].219 220## License221 222[MIT][license] © [Titus Wormer][author]223 224<!-- Definitions -->225 226[build-badge]: https://github.com/wooorm/parse-entities/workflows/main/badge.svg227 228[build]: https://github.com/wooorm/parse-entities/actions229 230[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/parse-entities.svg231 232[coverage]: https://codecov.io/github/wooorm/parse-entities233 234[downloads-badge]: https://img.shields.io/npm/dm/parse-entities.svg235 236[downloads]: https://www.npmjs.com/package/parse-entities237 238[size-badge]: https://img.shields.io/bundlephobia/minzip/parse-entities.svg239 240[size]: https://bundlephobia.com/result?p=parse-entities241 242[npm]: https://docs.npmjs.com/cli/install243 244[esmsh]: https://esm.sh245 246[license]: license247 248[author]: https://wooorm.com249 250[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c251 252[typescript]: https://www.typescriptlang.org253 254[warning]: #function-warningreason-point-code255 256[text]: #function-textvalue-position257 258[reference]: #function-referencevalue-position-source259 260[invalid]: https://github.com/wooorm/character-reference-invalid261 262[point]: https://github.com/syntax-tree/unist#point263 264[position]: https://github.com/syntax-tree/unist#position265 266[contribute]: https://opensource.guide/how-to-contribute/267