JS-YAML - YAML 1.2 parser and serializer for JavaScript

Build Status

Online Demo

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.

Breaking changes in 1.x.x -> 2.0.x

If your have not used custom tags or loader classes - no changes needed. Just upgrade library and enjoy high parse speed.

In other case, you should rewrite your tag constructors and custom loader classes, to conform new schema-based API. See examples and wiki for details. Note, that parser internals were completely rewritten.

Installation

YAML module for node.js

  1. npm install js-yaml

CLI executable

If you want to inspect your YAML files from CLI, install js-yaml globally:

  1. npm install js-yaml -g

Usage

  1. usage: js-yaml [-h] [-v] [-c] [-j] [-t] file
  3. Positional arguments:
  4.   file           File with YAML document(s)
  6. Optional arguments:
  7.   -h, --help     Show this help message and exit.
  8.   -v, --version  Show program's version number and exit.
  9.   -c, --compact  Display errors in compact mode
  10.   -j, --to-json  Output a non-funky boring JSON
  11.   -t, --trace    Show stack trace on error

Bundled YAML library for browsers

  1. <script src="js-yaml.min.js"></script>
  2. <script type="text/javascript">
  3. var doc = jsyaml.load('greeting: hello\nname: world');
  4. </script>

Browser support was done mostly for 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.

API

Here we cover the most ‘useful’ methods. If you need advanced details (creating your own tags), see wiki and examples for more info.

In node.js JS-YAML automatically registers handlers for .yml and .yaml files. You can load them just with require. That’s mostly equivalent to calling load() on fetched content of a file. Just with one string!

  1. require('js-yaml');
  3. // Get document, or throw exception on error
  4. try {
  5.   var doc = require('/home/ixti/example.yml');
  6.   console.log(doc);
  7. } catch (e) {
  8.   console.log(e);
  9. }

load (string [ , options ])

Parses string as single YAML document. Returns a JavaScript object or throws YAMLException on error.

NOTE: This function does not understands multi-document sources, it throws exception on those.

options:

  • filename (default: null) - string to be used as a file path in error/warning messages.
  • strict (default - false) makes the loader to throw errors instead of warnings.
  • schema (default: DEFAULT_SCHEMA) - specifies a schema to use.

loadAll (string, iterator [ , options ])

Same as load(), but understands multi-document sources and apply iterator to each document.

  1. var yaml = require('js-yaml');
  3. yaml.loadAll(data, function (doc) {
  4.   console.log(doc);
  5. });

safeLoad (string [ , options ])

Same as load() but uses SAFE_SCHEMA by default - only recommended tags of YAML specification (no JavaScript-specific tags, e.g. !!js/regexp).

safeLoadAll (string, iterator [ , options ])

Same as loadAll() but uses SAFE_SCHEMA by default - only recommended tags of YAML specification (no JavaScript-specific tags, e.g. !!js/regexp).

dump (object [ , options ])

Serializes object as YAML document.

options:

  • indent (default: 2) - indentation width to use (in spaces).
  • 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_SCHEMA) specifies a schema to use.

styles:

  1. !!null
  2.   "canonical"   => "~"
  4. !!int
  5.   "binary"      => "0b1", "0b101010", "0b1110001111010"
  6.   "octal"       => "01", "052", "016172"
  7.   "decimal"     => "1", "42", "7290"
  8.   "hexadecimal" => "0x1", "0x2A", "0x1C7A"
  10. !!null, !!bool, !!float
  11.   "lowercase"   => "null", "true", "false", ".nan", '.inf'
  12.   "uppercase"   => "NULL", "TRUE", "FALSE", ".NAN", '.INF'
  13.   "camelcase"   => "Null", "True", "False", ".NaN", '.Inf'

By default, !!int uses decimal, and !!null, !!bool, !!float use lowercase.

safeDump (object [ , options ])

Same as dump() but uses SAFE_SCHEMA by default - only recommended tags of YAML specification (no JavaScript-specific tags, e.g. !!js/regexp).

Supported YAML types

The list of standard YAML tags and corresponding JavaScipt types. See also YAML tag discussion and YAML types repository.

  1. !!null ''                   # null
  2. !!bool 'yes'                # bool
  3. !!int '3...'                # number
  4. !!float '3.14...'           # number
  5. !!binary '...base64...'     # buffer
  6. !!timestamp 'YYYY-...'      # date
  7. !!omap [ ... ]              # array of key-value pairs
  8. !!pairs [ ... ]             # array or array pairs
  9. !!set { ... }               # array of objects with given keys and null values
  10. !!str '...'                 # string
  11. !!seq [ ... ]               # array
  12. !!map { ... }               # object

JavaScript-specific tags

  1. !!js/regexp /pattern/gim            # RegExp
  2. !!js/undefined ''                   # Undefined
  3. !!js/function 'function () {...}'   # Function

Caveats

Note, that you use arrays or objects as key in JS-YAML. JS do not allows objects or array as keys, and stringifies (by calling .toString method) them at the moment of adding them.

  1. ---
  2. ? [ foo, bar ]
  3. : - baz
  4. ? { foo: bar }
  5. : - baz
  6.   - baz
  1. { "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.

  1. &anchor foo:
  2.   foo: bar
  3.   *anchor: duplicate key
  4.   baz: bat
  5.   *anchor: duplicate key

License

View the LICENSE file (MIT).