JS-YAML - YAML 1.2 parser / writer for JavaScript¶ ↑
{Online Demo}[http://nodeca.github.com/js-yaml/]
This is an implementation of YAML, a human-friendly data serialization language. Started as PyYAML port, it was completely rewritten from scratch. Now it's very fast, and supports 1.2 spec.
Installation¶ ↑
YAML module for node.js¶ ↑
npm install js-yaml
CLI executable¶ ↑
If you want to inspect your YAML files from CLI, install js-yaml globally:
npm install -g js-yaml
Usage¶ ↑
usage: js-yaml [-h] [-v] [-c] [-t] file Positional arguments: file File with YAML document(s) Optional arguments: -h, --help Show this help message and exit. -v, --version Show program's version number and exit. -c, --compact Display errors in compact mode -t, --trace Show stack trace on error
Bundled YAML library for browsers¶ ↑
<!-- esprima required only for !!js/function --> <script src="esprima.js"></script> <script src="js-yaml.min.js"></script> <script type="text/javascript"> var doc = jsyaml.load('greeting: hello\nname: world'); </script>
Browser support was done mostly for the online demo. If you find any errors - feel free to send pull requests with fixes. Also note, that IE and other old browsers needs es5-shims to operate.
Notes:
-
We have no resources to support browserified version. Don't expect it to be well tested. Don't expect fast fixes if something goes wrong there.
-
!!js/function
in browser bundle will not work by default. If you really need it - loadesprima
parser first (via amd or directly). -
!!bin
in browser will returnArray
, because browsers do not support node.jsBuffer
and adding Buffer shims is completely useless on practice.
API¶ ↑
Here we cover the most 'useful' methods. If you need advanced details (creating your own tags), see wiki and examples for more info.
yaml = require('js-yaml'); fs = require('fs'); // Get document, or throw exception on error try { var doc = yaml.safeLoad(fs.readFileSync('/home/ixti/example.yml', 'utf8')); console.log(doc); } catch (e) { console.log(e); }
safeLoad (string [ , options ])¶ ↑
Recommended loading way. Parses string
as single YAML document. Returns a JavaScript object or throws YAMLException
on error. By default, does not support regexps, functions and undefined. This method is safe for untrusted data.
options:
-
filename
(default: null) - string to be used as a file path in error/warning messages. -
onWarning
(default: null) - function to call on warning messages. Loader will call this function with an instance ofYAMLException
for each warning. -
schema
(default:DEFAULT_SAFE_SCHEMA
) - specifies a schema to use. -
FAILSAFE_SCHEMA
- only strings, arrays and plain objects: www.yaml.org/spec/1.2/spec.html#id2802346 -
JSON_SCHEMA
- all JSON-supported types: www.yaml.org/spec/1.2/spec.html#id2803231 -
CORE_SCHEMA
- same asJSON_SCHEMA
: www.yaml.org/spec/1.2/spec.html#id2804923 -
DEFAULT_SAFE_SCHEMA
- all supported YAML types, without unsafe ones (!!js/undefined
,!!js/regexp
and!!js/function
): yaml.org/type/ -
DEFAULT_FULL_SCHEMA
- all supported YAML types. -
json
(default: false) - compatibility with JSON.parse behaviour. If true, then duplicate keys in a mapping will override values rather than throwing an error.
NOTE: This function does not understand multi-document sources, it throws exception on those.
NOTE: JS-YAML does not support schema-specific tag resolution restrictions. So, the JSON schema is not as strictly defined in the YAML specification. It allows numbers in any notation, use Null
and NULL
as null
, etc. The core schema also has no such restrictions. It allows binary notation for integers.
load (string [ , options ])¶ ↑
Use with care with untrusted sources. The same as safeLoad()
but uses DEFAULT_FULL_SCHEMA
by default - adds some JavaScript-specific types: !!js/function
, !!js/regexp
and !!js/undefined
. For untrusted sources, you must additionally validate object structure to avoid injections:
var untrusted_code = '"toString": !<tag:yaml.org,2002:js/function> "function (){very_evil_thing();}"'; // I'm just converting that string, what could possibly go wrong? require('js-yaml').load(untrusted_code) + ''
safeLoadAll (string [, iterator] [, options ])¶ ↑
Same as safeLoad()
, but understands multi-document sources. Applies iterator
to each document if specified, or returns array of documents.
var yaml = require('js-yaml'); yaml.safeLoadAll(data, function (doc) { console.log(doc); });
loadAll (string [, iterator] [ , options ])¶ ↑
Same as safeLoadAll()
but uses DEFAULT_FULL_SCHEMA
by default.
safeDump (object [ , options ])¶ ↑
Serializes object
as a YAML document. Uses DEFAULT_SAFE_SCHEMA
, so it will throw an exception if you try to dump regexps or functions. However, you can disable exceptions by setting the skipInvalid
option to true
.
options:
-
indent
(default: 2) - indentation width to use (in spaces). -
noArrayIndent
(default: false) - when true, will not add an indentation level to array elements -
skipInvalid
(default: false) - do not throw on invalid types (like function in the safe schema) and skip pairs and single values with such types. -
flowLevel
(default: -1) - specifies level of nesting, when to switch from block to flow style for collections. -1 means block style everwhere -
styles
- “tag” => “style” map. Each tag may have own set of styles. -
schema
(default:DEFAULT_SAFE_SCHEMA
) specifies a schema to use. -
sortKeys
(default:false
) - iftrue
, sort keys when dumping YAML. If a function, use the function to sort the keys. -
lineWidth
(default:80
) - set max line width. -
noRefs
(default:false
) - iftrue
, don't convert duplicate objects into references -
noCompatMode
(default:false
) - iftrue
don't try to be compatible with older yaml versions. Currently: don't quote “yes”, “no” and so on, as required for YAML 1.1 -
condenseFlow
(default:false
) - iftrue
flow sequences will be condensed, omitting the space betweena, b
. Eg.'[a,b]'
, and omitting the space betweenkey: value
and quoting the key. Eg.'{"a":b}'
Can be useful when using yaml for pretty URL query params as spaces are %-encoded.
The following table show availlable styles (e.g. “canonical”, “binary”…) available for each tag (.e.g. !!null, !!int …). Yaml output is shown on the right side after =>
(default setting) or ->
:
!!null "canonical" -> "~" "lowercase" => "null" "uppercase" -> "NULL" "camelcase" -> "Null" !!int "binary" -> "0b1", "0b101010", "0b1110001111010" "octal" -> "01", "052", "016172" "decimal" => "1", "42", "7290" "hexadecimal" -> "0x1", "0x2A", "0x1C7A" !!bool "lowercase" => "true", "false" "uppercase" -> "TRUE", "FALSE" "camelcase" -> "True", "False" !!float "lowercase" => ".nan", '.inf' "uppercase" -> ".NAN", '.INF' "camelcase" -> ".NaN", '.Inf'
Example:
safeDump (object, { 'styles': { '!!null': 'canonical' // dump null as ~ }, 'sortKeys': true // sort object keys });
dump (object [ , options ])¶ ↑
Same as safeDump()
but without limits (uses DEFAULT_FULL_SCHEMA
by default).
Supported YAML types¶ ↑
The list of standard YAML tags and corresponding JavaScipt types. See also YAML tag discussion and YAML types repository.
!!null '' # null !!bool 'yes' # bool !!int '3...' # number !!float '3.14...' # number !!binary '...base64...' # buffer !!timestamp 'YYYY-...' # date !!omap [ ... ] # array of key-value pairs !!pairs [ ... ] # array or array pairs !!set { ... } # array of objects with given keys and null values !!str '...' # string !!seq [ ... ] # array !!map { ... } # object
JavaScript-specific tags
!!js/regexp /pattern/gim # RegExp !!js/undefined '' # Undefined !!js/function 'function () {...}' # Function
Caveats¶ ↑
Note, that you use arrays or objects as key in JS-YAML. JS does not allow objects or arrays as keys, and stringifies (by calling toString()
method) them at the moment of adding them.
--- ? [ foo, bar ] : - baz ? { foo: bar } : - baz - baz
{ "foo,bar": ["baz"], "[object Object]": ["baz", "baz"] }
Also, reading of properties on implicit block mapping keys is not supported yet. So, the following YAML document cannot be loaded.
&anchor foo: foo: bar *anchor: duplicate key baz: bat *anchor: duplicate key
Breaking changes in 2.x.x -> 3.x.x¶ ↑
If you have not used custom tags or loader classes and not loaded yaml files via require()
, no changes are needed. Just upgrade the library.
Otherwise, you should:
-
Replace all occurrences of
require('xxxx.yml')
byfs.readFileSync()
+yaml.safeLoad()
. -
rewrite your custom tags constructors and custom loader classes, to conform the new API. See examples and wiki for details.
License¶ ↑
View the LICENSE file (MIT).