.config/coc/extensions/node_modules/coc-prettier/node_modules/js-yaml/README.md

   1 JS-YAML - YAML 1.2 parser / writer for JavaScript
   2 =================================================
   3
   4 [![Build Status](https://travis-ci.org/nodeca/js-yaml.svg?branch=master)](https://travis-ci.org/nodeca/js-yaml)
   5 [![NPM version](https://img.shields.io/npm/v/js-yaml.svg)](https://www.npmjs.org/package/js-yaml)
   6
   7 __[Online Demo](http://nodeca.github.com/js-yaml/)__
   8
   9
  10 This is an implementation of [YAML](http://yaml.org/), a human-friendly data
  11 serialization language. Started as [PyYAML](http://pyyaml.org/) port, it was
  12 completely rewritten from scratch. Now it's very fast, and supports 1.2 spec.
  13
  14
  15 Installation
  16 ------------
  17
  18 ### YAML module for node.js
  19
  20 ```
  21 npm install js-yaml
  22 ```
  23
  24
  25 ### CLI executable
  26
  27 If you want to inspect your YAML files from CLI, install js-yaml globally:
  28
  29 ```
  30 npm install -g js-yaml
  31 ```
  32
  33 #### Usage
  34
  35 ```
  36 usage: js-yaml [-h] [-v] [-c] [-t] file
  37
  38 Positional arguments:
  39   file           File with YAML document(s)
  40
  41 Optional arguments:
  42   -h, --help     Show this help message and exit.
  43   -v, --version  Show program's version number and exit.
  44   -c, --compact  Display errors in compact mode
  45   -t, --trace    Show stack trace on error
  46 ```
  47
  48
  49 ### Bundled YAML library for browsers
  50
  51 ``` html
  52 <!-- esprima required only for !!js/function -->
  53 <script src="esprima.js"></script>
  54 <script src="js-yaml.min.js"></script>
  55 <script type="text/javascript">
  56 var doc = jsyaml.load('greeting: hello\nname: world');
  57 </script>
  58 ```
  59
  60 Browser support was done mostly for the online demo. If you find any errors - feel
  61 free to send pull requests with fixes. Also note, that IE and other old browsers
  62 needs [es5-shims](https://github.com/kriskowal/es5-shim) to operate.
  63
  64 Notes:
  65
  66 1. We have no resources to support browserified version. Don't expect it to be
  67    well tested. Don't expect fast fixes if something goes wrong there.
  68 2. `!!js/function` in browser bundle will not work by default. If you really need
  69    it - load `esprima` parser first (via amd or directly).
  70 3. `!!bin` in browser will return `Array`, because browsers do not support
  71    node.js `Buffer` and adding Buffer shims is completely useless on practice.
  72
  73
  74 API
  75 ---
  76
  77 Here we cover the most 'useful' methods. If you need advanced details (creating
  78 your own tags), see [wiki](https://github.com/nodeca/js-yaml/wiki) and
  79 [examples](https://github.com/nodeca/js-yaml/tree/master/examples) for more
  80 info.
  81
  82 ``` javascript
  83 const yaml = require('js-yaml');
  84 const fs   = require('fs');
  85
  86 // Get document, or throw exception on error
  87 try {
  88   const doc = yaml.safeLoad(fs.readFileSync('/home/ixti/example.yml', 'utf8'));
  89   console.log(doc);
  90 } catch (e) {
  91   console.log(e);
  92 }
  93 ```
  94
  95
  96 ### safeLoad (string [ , options ])
  97
  98 **Recommended loading way.** Parses `string` as single YAML document. Returns either a
  99 plain object, a string or `undefined`, or throws `YAMLException` on error. By default, does
 100 not support regexps, functions and undefined. This method is safe for untrusted data.
 101
 102 options:
 103
 104 - `filename` _(default: null)_ - string to be used as a file path in
 105   error/warning messages.
 106 - `onWarning` _(default: null)_ - function to call on warning messages.
 107   Loader will call this function with an instance of `YAMLException` for each warning.
 108 - `schema` _(default: `DEFAULT_SAFE_SCHEMA`)_ - specifies a schema to use.
 109   - `FAILSAFE_SCHEMA` - only strings, arrays and plain objects:
 110     http://www.yaml.org/spec/1.2/spec.html#id2802346
 111   - `JSON_SCHEMA` - all JSON-supported types:
 112     http://www.yaml.org/spec/1.2/spec.html#id2803231
 113   - `CORE_SCHEMA` - same as `JSON_SCHEMA`:
 114     http://www.yaml.org/spec/1.2/spec.html#id2804923
 115   - `DEFAULT_SAFE_SCHEMA` - all supported YAML types, without unsafe ones
 116     (`!!js/undefined`, `!!js/regexp` and `!!js/function`):
 117     http://yaml.org/type/
 118   - `DEFAULT_FULL_SCHEMA` - all supported YAML types.
 119 - `json` _(default: false)_ - compatibility with JSON.parse behaviour. If true, then duplicate keys in a mapping will override values rather than throwing an error.
 120
 121 NOTE: This function **does not** understand multi-document sources, it throws
 122 exception on those.
 123
 124 NOTE: JS-YAML **does not** support schema-specific tag resolution restrictions.
 125 So, the JSON schema is not as strictly defined in the YAML specification.
 126 It allows numbers in any notation, use `Null` and `NULL` as `null`, etc.
 127 The core schema also has no such restrictions. It allows binary notation for integers.
 128
 129
 130 ### load (string [ , options ])
 131
 132 **Use with care with untrusted sources**. The same as `safeLoad()` but uses
 133 `DEFAULT_FULL_SCHEMA` by default - adds some JavaScript-specific types:
 134 `!!js/function`, `!!js/regexp` and `!!js/undefined`. For untrusted sources, you
 135 must additionally validate object structure to avoid injections:
 136
 137 ``` javascript
 138 const untrusted_code = '"toString": !<tag:yaml.org,2002:js/function> "function (){very_evil_thing();}"';
 139
 140 // I'm just converting that string, what could possibly go wrong?
 141 require('js-yaml').load(untrusted_code) + ''
 142 ```
 143
 144
 145 ### safeLoadAll (string [, iterator] [, options ])
 146
 147 Same as `safeLoad()`, but understands multi-document sources. Applies
 148 `iterator` to each document if specified, or returns array of documents.
 149
 150 ``` javascript
 151 const yaml = require('js-yaml');
 152
 153 yaml.safeLoadAll(data, function (doc) {
 154   console.log(doc);
 155 });
 156 ```
 157
 158
 159 ### loadAll (string [, iterator] [ , options ])
 160
 161 Same as `safeLoadAll()` but uses `DEFAULT_FULL_SCHEMA` by default.
 162
 163
 164 ### safeDump (object [ , options ])
 165
 166 Serializes `object` as a YAML document. Uses `DEFAULT_SAFE_SCHEMA`, so it will
 167 throw an exception if you try to dump regexps or functions. However, you can
 168 disable exceptions by setting the `skipInvalid` option to `true`.
 169
 170 options:
 171
 172 - `indent` _(default: 2)_ - indentation width to use (in spaces).
 173 - `noArrayIndent` _(default: false)_ - when true, will not add an indentation level to array elements
 174 - `skipInvalid` _(default: false)_ - do not throw on invalid types (like function
 175   in the safe schema) and skip pairs and single values with such types.
 176 - `flowLevel` (default: -1) - specifies level of nesting, when to switch from
 177   block to flow style for collections. -1 means block style everwhere
 178 - `styles` - "tag" => "style" map. Each tag may have own set of styles.
 179 - `schema` _(default: `DEFAULT_SAFE_SCHEMA`)_ specifies a schema to use.
 180 - `sortKeys` _(default: `false`)_ - if `true`, sort keys when dumping YAML. If a
 181   function, use the function to sort the keys.
 182 - `lineWidth` _(default: `80`)_ - set max line width.
 183 - `noRefs` _(default: `false`)_ - if `true`, don't convert duplicate objects into references
 184 - `noCompatMode` _(default: `false`)_ - if `true` don't try to be compatible with older
 185   yaml versions. Currently: don't quote "yes", "no" and so on, as required for YAML 1.1
 186 - `condenseFlow` _(default: `false`)_ - if `true` flow sequences will be condensed, omitting the space between `a, b`. Eg. `'[a,b]'`, and omitting the space between `key: value` and quoting the key. Eg. `'{"a":b}'` Can be useful when using yaml for pretty URL query params as spaces are %-encoded.
 187
 188 The following table show availlable styles (e.g. "canonical",
 189 "binary"...) available for each tag (.e.g. !!null, !!int ...). Yaml
 190 output is shown on the right side after `=>` (default setting) or `->`:
 191
 192 ``` none
 193 !!null
 194   "canonical"   -> "~"
 195   "lowercase"   => "null"
 196   "uppercase"   -> "NULL"
 197   "camelcase"   -> "Null"
 198
 199 !!int
 200   "binary"      -> "0b1", "0b101010", "0b1110001111010"
 201   "octal"       -> "01", "052", "016172"
 202   "decimal"     => "1", "42", "7290"
 203   "hexadecimal" -> "0x1", "0x2A", "0x1C7A"
 204
 205 !!bool
 206   "lowercase"   => "true", "false"
 207   "uppercase"   -> "TRUE", "FALSE"
 208   "camelcase"   -> "True", "False"
 209
 210 !!float
 211   "lowercase"   => ".nan", '.inf'
 212   "uppercase"   -> ".NAN", '.INF'
 213   "camelcase"   -> ".NaN", '.Inf'
 214 ```
 215
 216 Example:
 217
 218 ``` javascript
 219 safeDump (object, {
 220   'styles': {
 221     '!!null': 'canonical' // dump null as ~
 222   },
 223   'sortKeys': true        // sort object keys
 224 });
 225 ```
 226
 227 ### dump (object [ , options ])
 228
 229 Same as `safeDump()` but without limits (uses `DEFAULT_FULL_SCHEMA` by default).
 230
 231
 232 Supported YAML types
 233 --------------------
 234
 235 The list of standard YAML tags and corresponding JavaScipt types. See also
 236 [YAML tag discussion](http://pyyaml.org/wiki/YAMLTagDiscussion) and
 237 [YAML types repository](http://yaml.org/type/).
 238
 239 ```
 240 !!null ''                   # null
 241 !!bool 'yes'                # bool
 242 !!int '3...'                # number
 243 !!float '3.14...'           # number
 244 !!binary '...base64...'     # buffer
 245 !!timestamp 'YYYY-...'      # date
 246 !!omap [ ... ]              # array of key-value pairs
 247 !!pairs [ ... ]             # array or array pairs
 248 !!set { ... }               # array of objects with given keys and null values
 249 !!str '...'                 # string
 250 !!seq [ ... ]               # array
 251 !!map { ... }               # object
 252 ```
 253
 254 **JavaScript-specific tags**
 255
 256 ```
 257 !!js/regexp /pattern/gim            # RegExp
 258 !!js/undefined ''                   # Undefined
 259 !!js/function 'function () {...}'   # Function
 260 ```
 261
 262 Caveats
 263 -------
 264
 265 Note, that you use arrays or objects as key in JS-YAML. JS does not allow objects
 266 or arrays as keys, and stringifies (by calling `toString()` method) them at the
 267 moment of adding them.
 268
 269 ``` yaml
 270 ---
 271 ? [ foo, bar ]
 272 : - baz
 273 ? { foo: bar }
 274 : - baz
 275   - baz
 276 ```
 277
 278 ``` javascript
 279 { "foo,bar": ["baz"], "[object Object]": ["baz", "baz"] }
 280 ```
 281
 282 Also, reading of properties on implicit block mapping keys is not supported yet.
 283 So, the following YAML document cannot be loaded.
 284
 285 ``` yaml
 286 &anchor foo:
 287   foo: bar
 288   *anchor: duplicate key
 289   baz: bat
 290   *anchor: duplicate key
 291 ```
 292
 293
 294 js-yaml for enterprise
 295 ----------------------
 296
 297 Available as part of the Tidelift Subscription
 298
 299 The maintainers of js-yaml and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-js-yaml?utm_source=npm-js-yaml&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)