1 JS-YAML - YAML 1.2 parser / writer for JavaScript
2 =================================================
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)
7 __[Online Demo](http://nodeca.github.com/js-yaml/)__
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.
18 ### YAML module for node.js
27 If you want to inspect your YAML files from CLI, install js-yaml globally:
30 npm install -g js-yaml
36 usage: js-yaml [-h] [-v] [-c] [-t] file
39 file File with YAML document(s)
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
49 ### Bundled YAML library for browsers
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');
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.
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.
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
83 yaml = require('js-yaml');
86 // Get document, or throw exception on error
88 var doc = yaml.safeLoad(fs.readFileSync('/home/ixti/example.yml', 'utf8'));
96 ### safeLoad (string [ , options ])
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.
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.
121 NOTE: This function **does not** understand multi-document sources, it throws
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.
130 ### load (string [ , options ])
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:
138 var untrusted_code = '"toString": !<tag:yaml.org,2002:js/function> "function (){very_evil_thing();}"';
140 // I'm just converting that string, what could possibly go wrong?
141 require('js-yaml').load(untrusted_code) + ''
145 ### safeLoadAll (string, iterator [ , options ])
147 Same as `safeLoad()`, but understands multi-document sources and apply
148 `iterator` to each document.
151 var yaml = require('js-yaml');
153 yaml.safeLoadAll(data, function (doc) {
159 ### loadAll (string, iterator [ , options ])
161 Same as `safeLoadAll()` but uses `DEFAULT_FULL_SCHEMA` by default.
164 ### safeDump (object [ , options ])
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.
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
193 "binary" => "0b1", "0b101010", "0b1110001111010"
194 "octal" => "01", "052", "016172"
195 "decimal" => "1", "42", "7290"
196 "hexadecimal" => "0x1", "0x2A", "0x1C7A"
198 !!null, !!bool, !!float
199 "lowercase" => "null", "true", "false", ".nan", '.inf'
200 "uppercase" => "NULL", "TRUE", "FALSE", ".NAN", '.INF'
201 "camelcase" => "Null", "True", "False", ".NaN", '.Inf'
204 By default, !!int uses `decimal`, and !!null, !!bool, !!float use `lowercase`.
208 ### dump (object [ , options ])
210 Same as `safeDump()` but without limits (uses `DEFAULT_FULL_SCHEMA` by default).
216 The list of standard YAML tags and corresponding JavaScipt types. See also
217 [YAML tag discussion](http://pyyaml.org/wiki/YAMLTagDiscussion) and
218 [YAML types repository](http://yaml.org/type/).
223 !!int '3...' # number
224 !!float '3.14...' # number
225 !!binary '...base64...' # buffer
226 !!timestamp 'YYYY-...' # date
227 !!omap [ ... ] # array of key-value pairs
228 !!pairs [ ... ] # array or array pairs
229 !!set { ... } # array of objects with given keys and null values
231 !!seq [ ... ] # array
232 !!map { ... } # object
235 **JavaScript-specific tags**
238 !!js/regexp /pattern/gim # RegExp
239 !!js/undefined '' # Undefined
240 !!js/function 'function () {...}' # Function
246 Note, that you use arrays or objects as key in JS-YAML. JS does not allow objects
247 or array as keys, and stringifies (by calling .toString method) them at the
248 moment of adding them.
260 { "foo,bar": ["baz"], "[object Object]": ["baz", "baz"] }
263 Also, reading of properties on implicit block mapping keys is not supported yet.
264 So, the following YAML document cannot be loaded.
269 *anchor: duplicate key
271 *anchor: duplicate key
275 Breaking changes in 2.x.x -> 3.x.x
276 ----------------------------------
278 If you have not used __custom__ tags or loader classes and not loaded yaml
279 files via `require()` - no changes needed. Just upgrade library.
281 Otherwise, you should:
283 1. Replace all occurences of `require('xxxx.yml')` by `fs.readFileSync()` +
285 2. rewrite your custom tags constructors and custom loader
286 classes, to conform new API. See
287 [examples](https://github.com/nodeca/js-yaml/tree/master/examples) and
288 [wiki](https://github.com/nodeca/js-yaml/wiki) for details.
294 View the [LICENSE](https://github.com/nodeca/js-yaml/blob/master/LICENSE) file