yaml 1.0.0-rc.6 → 1.0.1

package/README.md

@@ -1,5 +1,121 @@
-# YAML
+# YAML <a href="https://www.npmjs.com/package/yaml"><img align="right" src="https://badge.fury.io/js/yaml.svg" title="npm package" /></a><a href="https://travis-ci.org/eemeli/yaml"><img align="right" src="https://travis-ci.org/eemeli/yaml.svg?branch=master" title="Build status" /></a>
 
-JavaScript parser and stringifier for [YAML 1.2](http://yaml.org/). See the project's [documentation site](https://eemeli.org/yaml/) for more information.
+`yaml` is a JavaScript parser and stringifier for [YAML](http://yaml.org/), a human friendly data serialization standard. It supports both parsing and stringifying data using all versions of YAML, along with all common data schemas. As a particularly distinguishing feature, `yaml` fully supports reading and writing comments in YAML documents.
+
+The library is released under the ISC open source license, and the code is [available on GitHub](https://github.com/eemeli/yaml/). It has no external dependencies, and is usable in both browser and node environments.
+
+For more information, see the project's documentation site: [**eemeli.org/yaml**](https://eemeli.org/yaml/)
+
+> To install:
+
+```sh
+npm install yaml
+# or
+yarn add yaml
+```
 
 Note: `yaml` 0.x and 1.x are rather different implementations. For the earlier `yaml`, see [tj/js-yaml](https://github.com/tj/js-yaml).
+
+## API Overview
+
+The API provided by `yaml` has three layers, depending on how deep you need to go: [Pure JavaScript](https://eemeli.org/yaml/#pure-javascript), [YAML Documents](https://eemeli.org/yaml/#yaml-documents), and the [CST Parser](https://eemeli.org/yaml/#cst-parser). The first has the simplest API and "just works", the second gets you all the bells and whistles supported by the library along with a decent AST, and the third is the closest to YAML source, making it fast, raw, and crude.
+
+```js
+import YAML from 'yaml'
+// or
+const YAML = require('yaml')
+```
+
+### Pure JavaScript
+
+* [`YAML.parse(str, options): value`](https://eemeli.org/yaml/#yaml-parse)
+* [`YAML.stringify(value, options): string`](https://eemeli.org/yaml/#yaml-stringify)
+
+### YAML Documents
+
+* [`YAML.createNode(value, wrapScalars): Node`](https://eemeli.org/yaml/#creating-nodes)
+* [`YAML.defaultOptions`](https://eemeli.org/yaml/#options)
+* [`YAML.Document`](https://eemeli.org/yaml/#yaml-documents)
+  * [`constructor(options)`](https://eemeli.org/yaml/#creating-documents)
+  * [`defaults`](https://eemeli.org/yaml/#options)
+  * [`#anchors`](https://eemeli.org/yaml/#working-with-anchors)
+  * [`#contents`](https://eemeli.org/yaml/#content-nodes)
+  * [`#errors`](https://eemeli.org/yaml/#errors)
+* [`YAML.parseAllDocuments(str, options): YAML.Document[]`](https://eemeli.org/yaml/#parsing-documents)
+* [`YAML.parseDocument(str, options): YAML.Document`](https://eemeli.org/yaml/#parsing-documents)
+
+```js
+import Map from 'yaml/map'
+import Pair from 'yaml/pair'
+import Seq from 'yaml/seq'
+```
+
+* [`new Map()`](https://eemeli.org/yaml/#creating-nodes)
+* [`new Pair(key, value)`](https://eemeli.org/yaml/#creating-nodes)
+* [`new Seq()`](https://eemeli.org/yaml/#creating-nodes)
+
+### CST Parser
+
+```js
+import parseCST from 'yaml/parse-cst'
+```
+
+* [`parseCST(str): CSTDocument[]`](https://eemeli.org/yaml/#parsecst)
+* [`YAML.parseCST(str): CSTDocument[]`](https://eemeli.org/yaml/#parsecst)
+
+## YAML.parse
+
+```yaml
+# file.yml
+YAML:
+  - A human-readable data serialization language
+  - https://en.wikipedia.org/wiki/YAML
+yaml:
+  - A complete JavaScript implementation
+  - https://www.npmjs.com/package/yaml
+```
+
+```js
+import fs from 'fs'
+import YAML from 'yaml'
+
+YAML.parse('3.14159')
+// 3.14159
+
+YAML.parse('[ true, false, maybe, null ]\n')
+// [ true, false, 'maybe', null ]
+
+const file = fs.readFileSync('./file.yml', 'utf8')
+YAML.parse(file)
+// { YAML:
+//   [ 'A human-readable data serialization language',
+//     'https://en.wikipedia.org/wiki/YAML' ],
+//   yaml:
+//   [ 'A complete JavaScript implementation',
+//     'https://www.npmjs.com/package/yaml' ] }
+```
+
+## YAML.stringify
+
+```js
+import YAML from 'yaml'
+
+YAML.stringify(3.14159)
+// '3.14159\n'
+
+YAML.stringify([true, false, 'maybe', null])
+// `- true
+// - false
+// - maybe
+// - null
+// `
+
+YAML.stringify({ number: 3, plain: 'string', block: 'two\nlines\n' })
+// `number: 3
+// plain: string
+// block: >
+//   two
+//
+//   lines
+// `
+```

package/dist/Anchors.js

@@ -17,132 +17,102 @@ var _Seq = _interopRequireDefault(require("./schema/Seq"));
 
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
-function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
-
-function _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, descriptor.key, descriptor); } }
-
-function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); return Constructor; }
-
 function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
 
-var Anchors =
-/*#__PURE__*/
-function () {
-  function Anchors() {
-    _classCallCheck(this, Anchors);
-
+class Anchors {
+  constructor() {
     _defineProperty(this, "map", {});
   }
 
-  _createClass(Anchors, [{
-    key: "createAlias",
-    value: function createAlias(node, name) {
-      this.setAnchor(node, name);
-      return new _Alias.default(node);
-    }
-  }, {
-    key: "createMergePair",
-    value: function createMergePair() {
-      var _this = this;
+  static validAnchorNode(node) {
+    return node instanceof _Scalar.default || node instanceof _Seq.default || node instanceof _Map.default;
+  }
 
-      var merge = new _Merge.default();
+  createAlias(node, name) {
+    this.setAnchor(node, name);
+    return new _Alias.default(node);
+  }
 
-      for (var _len = arguments.length, sources = new Array(_len), _key = 0; _key < _len; _key++) {
-        sources[_key] = arguments[_key];
+  createMergePair(...sources) {
+    const merge = new _Merge.default();
+    merge.value.items = sources.map(s => {
+      if (s instanceof _Alias.default) {
+        if (s.source instanceof _Map.default) return s;
+      } else if (s instanceof _Map.default) {
+        return this.createAlias(s);
       }
 
-      merge.value.items = sources.map(function (s) {
-        if (s instanceof _Alias.default) {
-          if (s.source instanceof _Map.default) return s;
-        } else if (s instanceof _Map.default) {
-          return _this.createAlias(s);
-        }
+      throw new Error('Merge sources must be Map nodes or their Aliases');
+    });
+    return merge;
+  }
 
-        throw new Error('Merge sources must be Map nodes or their Aliases');
-      });
-      return merge;
-    }
-  }, {
-    key: "getName",
-    value: function getName(node) {
-      var map = this.map;
-      return Object.keys(map).find(function (a) {
-        return map[a] === node;
-      });
-    }
-  }, {
-    key: "getNode",
-    value: function getNode(name) {
-      return this.map[name];
+  getName(node) {
+    const map = this.map;
+    return Object.keys(map).find(a => map[a] === node);
+  }
+
+  getNode(name) {
+    return this.map[name];
+  }
+
+  newName(prefix) {
+    const names = Object.keys(this.map);
+
+    for (let i = 1; true; ++i) {
+      const name = `${prefix}${i}`;
+      if (!names.includes(name)) return name;
     }
-  }, {
-    key: "newName",
-    value: function newName(prefix) {
-      var names = Object.keys(this.map);
-
-      for (var i = 1; true; ++i) {
-        var name = "".concat(prefix).concat(i);
-        if (!names.includes(name)) return name;
-      }
-    } // During parsing, map & aliases contain CST nodes
+  } // During parsing, map & aliases contain CST nodes
+
 
-  }, {
-    key: "resolveNodes",
-    value: function resolveNodes() {
-      var map = this.map,
+  resolveNodes() {
+    const map = this.map,
           _cstAliases = this._cstAliases;
-      Object.keys(map).forEach(function (a) {
-        map[a] = map[a].resolved;
-      });
+    Object.keys(map).forEach(a => {
+      map[a] = map[a].resolved;
+    });
 
-      _cstAliases.forEach(function (a) {
-        a.source = a.source.resolved;
-      });
+    _cstAliases.forEach(a => {
+      a.source = a.source.resolved;
+    });
 
-      delete this._cstAliases;
+    delete this._cstAliases;
+  }
+
+  setAnchor(node, name) {
+    if (node != null && !Anchors.validAnchorNode(node)) {
+      throw new Error('Anchors may only be set for Scalar, Seq and Map nodes');
     }
-  }, {
-    key: "setAnchor",
-    value: function setAnchor(node, name) {
-      if (node != null && !Anchors.validAnchorNode(node)) {
-        throw new Error('Anchors may only be set for Scalar, Seq and Map nodes');
-      }
 
-      if (name && /[\x00-\x19\s,[\]{}]/.test(name)) {
-        throw new Error('Anchor names must not contain whitespace or control characters');
-      }
+    if (name && /[\x00-\x19\s,[\]{}]/.test(name)) {
+      throw new Error('Anchor names must not contain whitespace or control characters');
+    }
 
-      var map = this.map;
-      var prev = node && Object.keys(map).find(function (a) {
-        return map[a] === node;
-      });
-
-      if (prev) {
-        if (!name) {
-          return prev;
-        } else if (prev !== name) {
-          delete map[prev];
-          map[name] = node;
-        }
-      } else {
-        if (!name) {
-          if (!node) return null;
-          name = this.newName('a');
-        }
+    const map = this.map;
+    const prev = node && Object.keys(map).find(a => map[a] === node);
 
+    if (prev) {
+      if (!name) {
+        return prev;
+      } else if (prev !== name) {
+        delete map[prev];
         map[name] = node;
       }
+    } else {
+      if (!name) {
+        if (!node) return null;
+        name = this.newName('a');
+      }
 
-      return name;
+      map[name] = node;
     }
-  }], [{
-    key: "validAnchorNode",
-    value: function validAnchorNode(node) {
-      return node instanceof _Scalar.default || node instanceof _Seq.default || node instanceof _Map.default;
-    }
-  }]);
 
-  return Anchors;
-}();
+    return name;
+  }
+
+}
 
-exports.default = Anchors;
+exports.default = Anchors;
+module.exports = exports.default;
+module.exports.default = exports.default;