.config/coc/extensions/node_modules/coc-prettier/node_modules/parse-entities/readme.md

   1 # parse-entities
   2
   3 [![Build][build-badge]][build]
   4 [![Coverage][coverage-badge]][coverage]
   5 [![Downloads][downloads-badge]][downloads]
   6 [![Size][size-badge]][size]
   7
   8 Parse HTML character references: fast, spec-compliant, positional
   9 information.
  10
  11 ## Installation
  12
  13 [npm][]:
  14
  15 ```bash
  16 npm install parse-entities
  17 ```
  18
  19 ## Usage
  20
  21 ```js
  22 var decode = require('parse-entities')
  23
  24 decode('alpha &amp bravo')
  25 // => alpha & bravo
  26
  27 decode('charlie &copycat; delta')
  28 // => charlie ©cat; delta
  29
  30 decode('echo &copy; foxtrot &#8800; golf &#x1D306; hotel')
  31 // => echo © foxtrot ≠ golf 𝌆 hotel
  32 ```
  33
  34 ## API
  35
  36 ## `parseEntities(value[, options])`
  37
  38 ##### `options`
  39
  40 ###### `options.additional`
  41
  42 Additional character to accept (`string?`, default: `''`).
  43 This allows other characters, without error, when following an ampersand.
  44
  45 ###### `options.attribute`
  46
  47 Whether to parse `value` as an attribute value (`boolean?`, default:
  48 `false`).
  49
  50 ###### `options.nonTerminated`
  51
  52 Whether to allow non-terminated entities (`boolean`, default: `true`).
  53 For example, `&copycat` for `©cat`.  This behaviour is spec-compliant but
  54 can lead to unexpected results.
  55
  56 ###### `options.warning`
  57
  58 Error handler ([`Function?`][warning]).
  59
  60 ###### `options.text`
  61
  62 Text handler ([`Function?`][text]).
  63
  64 ###### `options.reference`
  65
  66 Reference handler ([`Function?`][reference]).
  67
  68 ###### `options.warningContext`
  69
  70 Context used when invoking `warning` (`'*'`, optional).
  71
  72 ###### `options.textContext`
  73
  74 Context used when invoking `text` (`'*'`, optional).
  75
  76 ###### `options.referenceContext`
  77
  78 Context used when invoking `reference` (`'*'`, optional)
  79
  80 ###### `options.position`
  81
  82 Starting `position` of `value` (`Location` or `Position`, optional).  Useful
  83 when dealing with values nested in some sort of syntax tree.  The default is:
  84
  85 ```js
  86 {
  87   start: {line: 1, column: 1, offset: 0},
  88   indent: []
  89 }
  90 ```
  91
  92 ##### Returns
  93
  94 `string` — Decoded `value`.
  95
  96 ### `function warning(reason, position, code)`
  97
  98 Error handler.
  99
 100 ##### Context
 101
 102 `this` refers to `warningContext` when given to `parseEntities`.
 103
 104 ##### Parameters
 105
 106 ###### `reason`
 107
 108 Human-readable reason for triggering a parse error (`string`).
 109
 110 ###### `position`
 111
 112 Place at which the parse error occurred (`Position`).
 113
 114 ###### `code`
 115
 116 Identifier of reason for triggering a parse error (`number`).
 117
 118 The following codes are used:
 119
 120 | Code | Example            | Note                                          |
 121 | ---- | ------------------ | --------------------------------------------- |
 122 | `1`  | `foo &amp bar`     | Missing semicolon (named)                     |
 123 | `2`  | `foo &#123 bar`    | Missing semicolon (numeric)                   |
 124 | `3`  | `Foo &bar baz`     | Ampersand did not start a reference           |
 125 | `4`  | `Foo &#`           | Empty reference                               |
 126 | `5`  | `Foo &bar; baz`    | Unknown entity                                |
 127 | `6`  | `Foo &#128; baz`   | [Disallowed reference][invalid]               |
 128 | `7`  | `Foo &#xD800; baz` | Prohibited: outside permissible unicode range |
 129
 130 ### `function text(value, location)`
 131
 132 Text handler.
 133
 134 ##### Context
 135
 136 `this` refers to `textContext` when given to `parseEntities`.
 137
 138 ##### Parameters
 139
 140 ###### `value`
 141
 142 String of content (`string`).
 143
 144 ###### `location`
 145
 146 Location at which `value` starts and ends (`Location`).
 147
 148 ### `function reference(value, location, source)`
 149
 150 Character reference handler.
 151
 152 ##### Context
 153
 154 `this` refers to `referenceContext` when given to `parseEntities`.
 155
 156 ##### Parameters
 157
 158 ###### `value`
 159
 160 Encoded character reference (`string`).
 161
 162 ###### `location`
 163
 164 Location at which `value` starts and ends (`Location`).
 165
 166 ###### `source`
 167
 168 Source of character reference (`Location`).
 169
 170 ## Related
 171
 172 *   [`stringify-entities`](https://github.com/wooorm/stringify-entities)
 173     — Encode HTML character references
 174 *   [`character-entities`](https://github.com/wooorm/character-entities)
 175     — Info on character entities
 176 *   [`character-entities-html4`](https://github.com/wooorm/character-entities-html4)
 177     — Info on HTML4 character entities
 178 *   [`character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)
 179     — Info on legacy character entities
 180 *   [`character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)
 181     — Info on invalid numeric character references
 182
 183 ## License
 184
 185 [MIT][license] © [Titus Wormer][author]
 186
 187 <!-- Definitions -->
 188
 189 [build-badge]: https://img.shields.io/travis/wooorm/parse-entities.svg
 190
 191 [build]: https://travis-ci.org/wooorm/parse-entities
 192
 193 [coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/parse-entities.svg
 194
 195 [coverage]: https://codecov.io/github/wooorm/parse-entities
 196
 197 [downloads-badge]: https://img.shields.io/npm/dm/parse-entities.svg
 198
 199 [downloads]: https://www.npmjs.com/package/parse-entities
 200
 201 [size-badge]: https://img.shields.io/bundlephobia/minzip/parse-entities.svg
 202
 203 [size]: https://bundlephobia.com/result?p=parse-entities
 204
 205 [npm]: https://docs.npmjs.com/cli/install
 206
 207 [license]: license
 208
 209 [author]: https://wooorm.com
 210
 211 [warning]: #function-warningreason-position-code
 212
 213 [text]: #function-textvalue-location
 214
 215 [reference]: #function-referencevalue-location-source
 216
 217 [invalid]: https://github.com/wooorm/character-reference-invalid