planning

node_modules/stringify-entities/readme.md

@@ -0,0 +1,160 @@
+# stringify-entities
+
+[![Build Status][build-badge]][build-status]
+[![Coverage Status][coverage-badge]][coverage-status]
+[![Downloads][downloads-badge]][downloads]
+[![Size][size-badge]][size]
+
+Encode HTML character references.
+
+*   [x] Very fast
+*   [x] Just the encoding part
+*   [x] Has either all the options you need for a minifier/prettifier, or a tiny
+    size w/ `stringify-entities/light`
+*   [x] Reliable: ``'`'`` characters are escaped to ensure no scripts
+    run in Internet Explorer 6 to 8.
+    Additionally, only named references recognized by HTML4 are encoded, meaning
+    the infamous `'` (which people think is a [virus][]) won’t show up
+
+## Algorithm
+
+By default, all dangerous, non-ASCII, and non-printable ASCII characters are
+encoded.
+A [subset][] of characters can be given to encode just those characters.
+Alternatively, pass [`escapeOnly`][escapeonly] to escape just the dangerous
+characters (`"`, `'`, `<`, `>`, `&`, `` ` ``).
+By default, hexadecimal character references are used.
+Pass [`useNamedReferences`][named] to use named character references when
+possible, or [`useShortestReferences`][short] to use whichever is shortest:
+decimal, hexadecimal, or named.
+There is also a `stringify-entities/light` module, which works just like
+`stringifyEntities` but without the formatting options: it’s much smaller but
+always outputs hexadecimal character references.
+
+## Install
+
+[npm][]:
+
+```sh
+npm install stringify-entities
+```
+
+## Use
+
+```js
+var stringify = require('stringify-entities')
+
+stringify('alpha © bravo ≠ charlie 𝌆 delta')
+// => 'alpha &#xA9; bravo &#x2260; charlie &#x1D306; delta'
+
+stringify('alpha © bravo ≠ charlie 𝌆 delta', {useNamedReferences: true})
+// => 'alpha &copy; bravo &ne; charlie &#x1D306; delta'
+```
+
+## API
+
+### `stringifyEntities(value[, options])`
+
+Encode special characters in `value`.
+
+##### `options`
+
+##### Core options
+
+###### `options.escapeOnly`
+
+Whether to only escape possibly dangerous characters (`boolean`, default:
+`false`).
+Those characters are `"`, `&`, `'`, `<`, `>`, and `` ` ``.
+
+###### `options.subset`
+
+Whether to only escape the given subset of characters (`Array.<string>`).
+Note that only BMP characters are supported here (so no emoji).
+
+##### Formatting options
+
+If you do not care about these, use `stringify-entities/light`, which always
+outputs hexadecimal character references.
+
+###### `options.useNamedReferences`
+
+Prefer named character references (`&amp;`) where possible (`boolean?`, default:
+`false`).
+
+###### `options.useShortestReferences`
+
+Prefer the shortest possible reference, if that results in less bytes
+(`boolean?`, default: `false`).
+**Note**: `useNamedReferences` can be omitted when using
+`useShortestReferences`.
+
+###### `options.omitOptionalSemicolons`
+
+Whether to omit semicolons when possible (`boolean?`, default: `false`).
+**Note**: This creates what HTML calls “parse errors” but is otherwise still
+valid HTML — don’t use this except when building a minifier.
+
+Omitting semicolons is possible for [legacy][] named references in
+[certain][dangerous] cases, and numeric references in some cases.
+
+###### `options.attribute`
+
+Only needed when operating dangerously with `omitOptionalSemicolons: true`.
+Create character references which don’t fail in attributes (`boolean?`, default:
+`false`).
+
+## Related
+
+*   [`parse-entities`](https://github.com/wooorm/parse-entities)
+    — Parse 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 HTML 4 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/stringify-entities.svg
+
+[build-status]: https://travis-ci.org/wooorm/stringify-entities
+
+[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/stringify-entities.svg
+
+[coverage-status]: https://codecov.io/github/wooorm/stringify-entities
+
+[downloads-badge]: https://img.shields.io/npm/dm/stringify-entities.svg
+
+[downloads]: https://www.npmjs.com/package/stringify-entities
+
+[size-badge]: https://img.shields.io/bundlephobia/minzip/stringify-entities.svg
+
+[size]: https://bundlephobia.com/result?p=stringify-entities
+
+[license]: license
+
+[author]: https://wooorm.com
+
+[npm]: https://docs.npmjs.com/cli/install
+
+[virus]: https://www.telegraph.co.uk/technology/advice/10516839/Why-do-some-apostrophes-get-replaced-with-andapos.html
+
+[dangerous]: lib/constant/dangerous.json
+
+[legacy]: https://github.com/wooorm/character-entities-legacy
+
+[subset]: #optionssubset
+
+[escapeonly]: #optionsescapeonly
+
+[named]: #optionsusenamedreferences
+
+[short]: #optionsuseshortestreferences