review.tizen.org Git - platform/framework/web/crosswalk-tizen.git/blob

   1 JS-YAML - YAML 1.2 parser and serializer 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 resourses 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
 120 NOTE: This function **does not** understand multi-document sources, it throws
 121 exception on those.
 122
 123 NOTE: JS-YAML **does not** support schema-specific tag resolution restrictions.
 124 So, JSON schema is not as strict as defined in the YAML specification.
 125 It allows numbers in any notaion, use `Null` and `NULL` as `null`, etc.
 126 Core schema also has no such restrictions. It allows binary notation for integers.
 127
 128
 129 ### load (string [ , options ])
 130
 131 **Use with care with untrusted sources**. The same as `safeLoad()` but uses
 132 `DEFAULT_FULL_SCHEMA` by default - adds some JavaScript-specific types:
 133 `!!js/function`, `!!js/regexp` and `!!js/undefined`. For untrusted sources you
 134 must additionally validate object structure, to avoid injections:
 135
 136 ``` javascript
 137 var untrusted_code = '"toString": !<tag:yaml.org,2002:js/function> "function (){very_evil_thing();}"';
 138
 139 // I'm just converting that string, what could possibly go wrong?
 140 require('js-yaml').load(untrusted_code) + ''
 141 ```
 142
 143
 144 ### safeLoadAll (string, iterator [ , options ])
 145
 146 Same as `safeLoad()`, but understands multi-document sources and apply
 147 `iterator` to each document.
 148
 149 ``` javascript
 150 var yaml = require('js-yaml');
 151
 152 yaml.safeLoadAll(data, function (doc) {
 153   console.log(doc);
 154 });
 155 ```
 156
 157
 158 ### loadAll (string, iterator [ , options ])
 159
 160 Same as `safeLoadAll()` but uses `DEFAULT_FULL_SCHEMA` by default.
 161
 162
 163 ### safeDump (object [ , options ])
 164
 165 Serializes `object` as YAML document. Uses `DEFAULT_SAFE_SCHEMA`, so it will
 166 throw exception if you try to dump regexps or functions. However, you can
 167 disable exceptions by `skipInvalid` option.
 168
 169 options:
 170
 171 - `indent` _(default: 2)_ - indentation width to use (in spaces).
 172 - `skipInvalid` _(default: false)_ - do not throw on invalid types (like function
 173   in the safe schema) and skip pairs and single values with such types.
 174 - `flowLevel` (default: -1) - specifies level of nesting, when to switch from
 175   block to flow style for collections. -1 means block style everwhere
 176 - `styles` - "tag" => "style" map. Each tag may have own set of styles.
 177 - `schema` _(default: `DEFAULT_SAFE_SCHEMA`)_ specifies a schema to use.
 178
 179 styles:
 180
 181 ``` none
 182 !!null
 183   "canonical"   => "~"
 184
 185 !!int
 186   "binary"      => "0b1", "0b101010", "0b1110001111010"
 187   "octal"       => "01", "052", "016172"
 188   "decimal"     => "1", "42", "7290"
 189   "hexadecimal" => "0x1", "0x2A", "0x1C7A"
 190
 191 !!null, !!bool, !!float
 192   "lowercase"   => "null", "true", "false", ".nan", '.inf'
 193   "uppercase"   => "NULL", "TRUE", "FALSE", ".NAN", '.INF'
 194   "camelcase"   => "Null", "True", "False", ".NaN", '.Inf'
 195 ```
 196
 197 By default, !!int uses `decimal`, and !!null, !!bool, !!float use `lowercase`.
 198
 199
 200
 201 ### dump (object [ , options ])
 202
 203 Same as `safeDump()` but without limits (uses `DEFAULT_FULL_SCHEMA` by default).
 204
 205
 206 Supported YAML types
 207 --------------------
 208
 209 The list of standard YAML tags and corresponding JavaScipt types. See also
 210 [YAML tag discussion](http://pyyaml.org/wiki/YAMLTagDiscussion) and
 211 [YAML types repository](http://yaml.org/type/).
 212
 213 ```
 214 !!null ''                   # null
 215 !!bool 'yes'                # bool
 216 !!int '3...'                # number
 217 !!float '3.14...'           # number
 218 !!binary '...base64...'     # buffer
 219 !!timestamp 'YYYY-...'      # date
 220 !!omap [ ... ]              # array of key-value pairs
 221 !!pairs [ ... ]             # array or array pairs
 222 !!set { ... }               # array of objects with given keys and null values
 223 !!str '...'                 # string
 224 !!seq [ ... ]               # array
 225 !!map { ... }               # object
 226 ```
 227
 228 **JavaScript-specific tags**
 229
 230 ```
 231 !!js/regexp /pattern/gim            # RegExp
 232 !!js/undefined ''                   # Undefined
 233 !!js/function 'function () {...}'   # Function
 234 ```
 235
 236 Caveats
 237 -------
 238
 239 Note, that you use arrays or objects as key in JS-YAML. JS do not allows objects
 240 or array as keys, and stringifies (by calling .toString method) them at the
 241 moment of adding them.
 242
 243 ``` yaml
 244 ---
 245 ? [ foo, bar ]
 246 : - baz
 247 ? { foo: bar }
 248 : - baz
 249   - baz
 250 ```
 251
 252 ``` javascript
 253 { "foo,bar": ["baz"], "[object Object]": ["baz", "baz"] }
 254 ```
 255
 256 Also, reading of properties on implicit block mapping keys is not supported yet.
 257 So, the following YAML document cannot be loaded.
 258
 259 ``` yaml
 260 &anchor foo:
 261   foo: bar
 262   *anchor: duplicate key
 263   baz: bat
 264   *anchor: duplicate key
 265 ```
 266
 267
 268 Breaking changes in 2.x.x -> 3.x.x
 269 ----------------------------------
 270
 271 If your have not used __custom__ tags or loader classes and not loaded yaml
 272 files via `require()` - no changes needed. Just upgrade library.
 273
 274 In other case, you should:
 275
 276 1. Replace all occurences of `require('xxxx.yml')` by `fs.readFileSync()` +
 277   `yaml.safeLoad()`.
 278 2. rewrite your custom tags constructors and custom loader
 279   classes, to conform new API. See
 280   [examples](https://github.com/nodeca/js-yaml/tree/master/examples) and
 281   [wiki](https://github.com/nodeca/js-yaml/wiki) for details.
 282
 283
 284 License
 285 -------
 286
 287 View the [LICENSE](https://github.com/nodeca/js-yaml/blob/master/LICENSE) file
 288 (MIT).