This repository has been archived on 2020-11-02. You can view files and clone it, but cannot push or open issues or pull requests.
TripSit_Suite/node_modules/parse-entities/readme.md

218 lines
5.1 KiB
Markdown
Raw Normal View History

# parse-entities
[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
Parse HTML character references: fast, spec-compliant, positional
information.
## Install
[npm][]:
```sh
npm install parse-entities
```
## Use
```js
var decode = require('parse-entities')
decode('alpha &amp bravo')
// => alpha & bravo
decode('charlie &copycat; delta')
// => charlie ©cat; delta
decode('echo © foxtrot ≠ golf 𝌆 hotel')
// => echo © foxtrot ≠ golf 𝌆 hotel
```
## API
## `parseEntities(value[, options])`
##### `options`
###### `options.additional`
Additional character to accept (`string?`, default: `''`).
This allows other characters, without error, when following an ampersand.
###### `options.attribute`
Whether to parse `value` as an attribute value (`boolean?`, default:
`false`).
###### `options.nonTerminated`
Whether to allow non-terminated entities (`boolean`, default: `true`).
For example, `&copycat` for `©cat`. This behaviour is spec-compliant but
can lead to unexpected results.
###### `options.warning`
Error handler ([`Function?`][warning]).
###### `options.text`
Text handler ([`Function?`][text]).
###### `options.reference`
Reference handler ([`Function?`][reference]).
###### `options.warningContext`
Context used when invoking `warning` (`'*'`, optional).
###### `options.textContext`
Context used when invoking `text` (`'*'`, optional).
###### `options.referenceContext`
Context used when invoking `reference` (`'*'`, optional)
###### `options.position`
Starting `position` of `value` (`Location` or `Position`, optional). Useful
when dealing with values nested in some sort of syntax tree. The default is:
```js
{
start: {line: 1, column: 1, offset: 0},
indent: []
}
```
##### Returns
`string` — Decoded `value`.
### `function warning(reason, position, code)`
Error handler.
##### Context
`this` refers to `warningContext` when given to `parseEntities`.
##### Parameters
###### `reason`
Human-readable reason for triggering a parse error (`string`).
###### `position`
Place at which the parse error occurred (`Position`).
###### `code`
Identifier of reason for triggering a parse error (`number`).
The following codes are used:
| Code | Example | Note |
| ---- | ------------------ | --------------------------------------------- |
| `1` | `foo &amp bar` | Missing semicolon (named) |
| `2` | `foo &#123 bar` | Missing semicolon (numeric) |
| `3` | `Foo &bar baz` | Ampersand did not start a reference |
| `4` | `Foo &#` | Empty reference |
| `5` | `Foo &bar; baz` | Unknown entity |
| `6` | `Foo € baz` | [Disallowed reference][invalid] |
| `7` | `Foo � baz` | Prohibited: outside permissible unicode range |
### `function text(value, location)`
Text handler.
##### Context
`this` refers to `textContext` when given to `parseEntities`.
##### Parameters
###### `value`
String of content (`string`).
###### `location`
Location at which `value` starts and ends (`Location`).
### `function reference(value, location, source)`
Character reference handler.
##### Context
`this` refers to `referenceContext` when given to `parseEntities`.
##### Parameters
###### `value`
Encoded character reference (`string`).
###### `location`
Location at which `value` starts and ends (`Location`).
###### `source`
Source of character reference (`Location`).
## Related
* [`stringify-entities`](https://github.com/wooorm/stringify-entities)
— Encode HTML character references
* [`character-entities`](https://github.com/wooorm/character-entities)
— Info on character entities
* [`character-entities-html4`](https://github.com/wooorm/character-entities-html4)
— Info on HTML4 character entities
* [`character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)
— Info on legacy character entities
* [`character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)
— Info on invalid numeric character references
## License
[MIT][license] © [Titus Wormer][author]
<!-- Definitions -->
[build-badge]: https://img.shields.io/travis/wooorm/parse-entities.svg
[build]: https://travis-ci.org/wooorm/parse-entities
[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/parse-entities.svg
[coverage]: https://codecov.io/github/wooorm/parse-entities
[downloads-badge]: https://img.shields.io/npm/dm/parse-entities.svg
[downloads]: https://www.npmjs.com/package/parse-entities
[size-badge]: https://img.shields.io/bundlephobia/minzip/parse-entities.svg
[size]: https://bundlephobia.com/result?p=parse-entities
[npm]: https://docs.npmjs.com/cli/install
[license]: license
[author]: https://wooorm.com
[warning]: #function-warningreason-position-code
[text]: #function-textvalue-location
[reference]: #function-referencevalue-location-source
[invalid]: https://github.com/wooorm/character-reference-invalid