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

   1 # stringify-entities [![Build Status][build-badge]][build-status] [![Coverage Status][coverage-badge]][coverage-status]
   2
   3 Encode HTML character references and character entities.
   4
   5 *   [x] Very fast
   6 *   [x] Just the encoding part
   7 *   [x] Reliable: ``'`'`` characters are escaped to ensure no scripts
   8     run in IE6-8.  Additionally, only named entities recognised by HTML4
   9     are encoded, meaning the infamous `&apos;` (which people think is a
  10     [virus][]) won’t show up
  11
  12 ## Algorithm
  13
  14 By default, all dangerous, non-ASCII, or non-printable ASCII characters
  15 are encoded.  A [subset][] of characters can be given to encode just
  16 those characters.  Alternatively, pass [`escapeOnly`][escapeonly] to
  17 escape just the dangerous characters (`"`, `'`, `<`, `>`, `&`, `` ` ``).
  18 By default, numeric entities are used.  Pass [`useNamedReferences`][named]
  19 to use named entities when possible, or [`useShortestReferences`][short]
  20 to use them if that results in less bytes.
  21
  22 ## Installation
  23
  24 [npm][]:
  25
  26 ```bash
  27 npm install stringify-entities
  28 ```
  29
  30 ## Usage
  31
  32 ```js
  33 var stringify = require('stringify-entities')
  34
  35 stringify('alpha © bravo ≠ charlie 𝌆 delta')
  36 // => 'alpha &#xA9; bravo &#x2260; charlie &#x1D306; delta'
  37
  38 stringify('alpha © bravo ≠ charlie 𝌆 delta', {useNamedReferences: true})
  39 // => 'alpha &copy; bravo &ne; charlie &#x1D306; delta'
  40 ```
  41
  42 ## API
  43
  44 ### `stringifyEntities(value[, options])`
  45
  46 Encode special characters in `value`.
  47
  48 ##### `options`
  49
  50 ###### `options.escapeOnly`
  51
  52 Whether to only escape possibly dangerous characters (`boolean`,
  53 default: `false`).  Those characters are `"`, `'`, `<`, `>` `&`, and
  54 `` ` ``.
  55
  56 ###### `options.subset`
  57
  58 Whether to only escape the given subset of characters (`Array.<string>`).
  59
  60 ###### `options.useNamedReferences`
  61
  62 Whether to use named entities where possible (`boolean?`, default:
  63 `false`).
  64
  65 ###### `options.useShortestReferences`
  66
  67 Whether to use named entities, where possible, if that results in less
  68 bytes (`boolean?`, default: `false`).  **Note**: `useNamedReferences`
  69 can be omitted when using `useShortestReferences`.
  70
  71 ###### `options.omitOptionalSemicolons`
  72
  73 Whether to omit semi-colons when possible (`boolean?`, default: `false`).
  74 **Note**: This creates parse errors: don’t use this except when building
  75 a minifier.
  76
  77 Omitting semi-colons is possible for [certain][dangerous] [legacy][]
  78 named references, and numeric entities, in some cases.
  79
  80 ###### `options.attribute`
  81
  82 Only needed when operating dangerously with `omitOptionalSemicolons: true`.
  83 Create entities which don’t fail in attributes (`boolean?`, default:
  84 `false`).
  85
  86 ## Related
  87
  88 *   [`parse-entities`](https://github.com/wooorm/parse-entities)
  89     — Parse HTML character references
  90 *   [`character-entities`](https://github.com/wooorm/character-entities)
  91     — Info on character entities
  92 *   [`character-entities-html4`](https://github.com/wooorm/character-entities-html4)
  93     — Info on HTML4 character entities
  94 *   [`character-entities-legacy`](https://github.com/wooorm/character-entities-legacy)
  95     — Info on legacy character entities
  96 *   [`character-reference-invalid`](https://github.com/wooorm/character-reference-invalid)
  97     — Info on invalid numeric character references
  98
  99 ## License
 100
 101 [MIT][license] © [Titus Wormer][author]
 102
 103 <!-- Definitions -->
 104
 105 [build-badge]: https://img.shields.io/travis/wooorm/stringify-entities.svg
 106
 107 [build-status]: https://travis-ci.org/wooorm/stringify-entities
 108
 109 [coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/stringify-entities.svg
 110
 111 [coverage-status]: https://codecov.io/github/wooorm/stringify-entities
 112
 113 [license]: LICENSE
 114
 115 [author]: http://wooorm.com
 116
 117 [npm]: https://docs.npmjs.com/cli/install
 118
 119 [virus]: http://www.telegraph.co.uk/technology/advice/10516839/Why-do-some-apostrophes-get-replaced-with-andapos.html
 120
 121 [dangerous]: dangerous.json
 122
 123 [legacy]: https://github.com/wooorm/character-entities-legacy
 124
 125 [subset]: #optionssubset
 126
 127 [escapeonly]: #optionsescapeonly
 128
 129 [named]: #optionsusenamedreferences
 130
 131 [short]: #optionsuseshortestreferences