www.aleph1.co.uk Git - yaffs-website/blob - 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 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 yaml = require('js-yaml');
  84 fs   = require('fs');
  85
  86 // Get document, or throw exception on error
  87 try {
  88   var 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 a JavaScript
  99 object or throws `YAMLException` on error. By default, does not support regexps,
 100 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 throw on warnings if this function is not provided.
 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, JSON schema is not as strict as defined in the YAML specification.
 126 It allows numbers in any notation, use `Null` and `NULL` as `null`, etc.
 127 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 var 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 and apply
 148 `iterator` to each document.
 149
 150 ``` javascript
 151 var 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 YAML document. Uses `DEFAULT_SAFE_SCHEMA`, so it will
 167 throw exception if you try to dump regexps or functions. However, you can
 168 disable exceptions by `skipInvalid` option.
 169
 170 options:
 171
 172 - `indent` _(default: 2)_ - indentation width to use (in spaces).
 173 - `skipInvalid` _(default: false)_ - do not throw on invalid types (like function
 174   in the safe schema) and skip pairs and single values with such types.
 175 - `flowLevel` (default: -1) - specifies level of nesting, when to switch from
 176   block to flow style for collections. -1 means block style everwhere
 177 - `styles` - "tag" => "style" map. Each tag may have own set of styles.
 178 - `schema` _(default: `DEFAULT_SAFE_SCHEMA`)_ specifies a schema to use.
 179 - `sortKeys` _(default: `false`)_ - if `true`, sort keys when dumping YAML. If a
 180   function, use the function to sort the keys.
 181 - `lineWidth` _(default: `80`)_ - set max line width.
 182 - `noRefs` _(default: `false`)_ - if `true`, don't convert duplicate objects into references
 183 - `noCompatMode` _(default: `false`)_ - if `true` don't try to be compatible with older
 184   yaml versions. Currently: don't quote "yes", "no" and so on, as required for YAML 1.1
 185
 186 The following table show availlable styles (e.g. "canonical",
 187 "binary"...) available for each tag (.e.g. !!null, !!int ...). Yaml
 188 ouput is shown on the right side after `=>` (default setting) or `->`:
 189
 190 ``` none
 191 !!null
 192   "canonical"   -> "~"
 193   "lowercase"   => "null"
 194   "uppercase"   -> "NULL"
 195   "camelcase"   -> "Null"
 196
 197 !!int
 198   "binary"      -> "0b1", "0b101010", "0b1110001111010"
 199   "octal"       -> "01", "052", "016172"
 200   "decimal"     => "1", "42", "7290"
 201   "hexadecimal" -> "0x1", "0x2A", "0x1C7A"
 202
 203 !!bool
 204   "lowercase"   => "true", "false"
 205   "uppercase"   -> "TRUE", "FALSE"
 206   "camelcase"   -> "True", "False"
 207
 208 !!float
 209   "lowercase"   => ".nan", '.inf'
 210   "uppercase"   -> ".NAN", '.INF'
 211   "camelcase"   -> ".NaN", '.Inf'
 212 ```
 213
 214 Example:
 215
 216 ``` javascript
 217 safeDump (object, {
 218   'styles': {
 219     '!!null': 'canonical' // dump null as ~
 220   },
 221   'sortKeys': true        // sort object keys
 222 }
 223 ```
 224
 225 ### dump (object [ , options ])
 226
 227 Same as `safeDump()` but without limits (uses `DEFAULT_FULL_SCHEMA` by default).
 228
 229
 230 Supported YAML types
 231 --------------------
 232
 233 The list of standard YAML tags and corresponding JavaScipt types. See also
 234 [YAML tag discussion](http://pyyaml.org/wiki/YAMLTagDiscussion) and
 235 [YAML types repository](http://yaml.org/type/).
 236
 237 ```
 238 !!null ''                   # null
 239 !!bool 'yes'                # bool
 240 !!int '3...'                # number
 241 !!float '3.14...'           # number
 242 !!binary '...base64...'     # buffer
 243 !!timestamp 'YYYY-...'      # date
 244 !!omap [ ... ]              # array of key-value pairs
 245 !!pairs [ ... ]             # array or array pairs
 246 !!set { ... }               # array of objects with given keys and null values
 247 !!str '...'                 # string
 248 !!seq [ ... ]               # array
 249 !!map { ... }               # object
 250 ```
 251
 252 **JavaScript-specific tags**
 253
 254 ```
 255 !!js/regexp /pattern/gim            # RegExp
 256 !!js/undefined ''                   # Undefined
 257 !!js/function 'function () {...}'   # Function
 258 ```
 259
 260 Caveats
 261 -------
 262
 263 Note, that you use arrays or objects as key in JS-YAML. JS does not allow objects
 264 or array as keys, and stringifies (by calling .toString method) them at the
 265 moment of adding them.
 266
 267 ``` yaml
 268 ---
 269 ? [ foo, bar ]
 270 : - baz
 271 ? { foo: bar }
 272 : - baz
 273   - baz
 274 ```
 275
 276 ``` javascript
 277 { "foo,bar": ["baz"], "[object Object]": ["baz", "baz"] }
 278 ```
 279
 280 Also, reading of properties on implicit block mapping keys is not supported yet.
 281 So, the following YAML document cannot be loaded.
 282
 283 ``` yaml
 284 &anchor foo:
 285   foo: bar
 286   *anchor: duplicate key
 287   baz: bat
 288   *anchor: duplicate key
 289 ```
 290
 291
 292 Breaking changes in 2.x.x -> 3.x.x
 293 ----------------------------------
 294
 295 If you have not used __custom__ tags or loader classes and not loaded yaml
 296 files via `require()` - no changes needed. Just upgrade library.
 297
 298 Otherwise, you should:
 299
 300 1. Replace all occurences of `require('xxxx.yml')` by `fs.readFileSync()` +
 301   `yaml.safeLoad()`.
 302 2. rewrite your custom tags constructors and custom loader
 303   classes, to conform new API. See
 304   [examples](https://github.com/nodeca/js-yaml/tree/master/examples) and
 305   [wiki](https://github.com/nodeca/js-yaml/wiki) for details.
 306
 307
 308 License
 309 -------
 310
 311 View the [LICENSE](https://github.com/nodeca/js-yaml/blob/master/LICENSE) file
 312 (MIT).