Revert "Removed the external-facing YAML object. All methods will now allow a YAML string to be passed-in instead"

This reverts commit 54af127.

Author: JamesMessinger

dist/ref-parser.js

@@ -27,6 +27,10 @@ Classes & Methods
 - [`get()`](refs.md#getref-options)
 - [`set()`](refs.md#setref-value-options)
 
+#### [`YAML`](yaml.md)
+- [`parse()`](yaml.md#parsetext)
+- [`stringify()`](yaml.md#stringifyvalue)
+
 #### [`Options`](options.md)
 
 

dist/ref-parser.js.map

@@ -0,0 +1,84 @@
+`YAML` object
+==========================
+
+This object provides simple YAML parsing functions.  JSON Schema $Ref Parser uses this object internally
+for its own YAML parsing, but it is also exposed so you can use it in your code if needed.
+
+
+### `parse(text)`
+
+- **text** (_required_) - `string`<br>
+The YAML string to be parsed.
+
+- **Return Value:**<br>
+Returns the parsed value, which can be any valid JSON type (object, array, string, number, etc.)
+
+This method is similar to [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse), but it supports YAML _in addition_ to JSON (since any JSON document is also a valid YAML document).
+
+```javascript
+var YAML = $RefParser.YAML;
+var text = "title: person \n" +
+           "required: \n" +
+           "  - name \n" +
+           "  - age \n" +
+           "properties: \n" +
+           "  name: \n" +
+           "    type: string \n" +
+           "  age: \n" +
+           "    type: number"
+
+var obj = YAML.parse(text);
+
+// {
+//   title: "person",
+//   required: ["name", "age"],
+//   properties: {
+//     name: {
+//       type: "string"
+//     },
+//     age: {
+//       type: "number"
+//     }
+//   }
+// }
+```
+
+
+### `stringify(value)`
+
+- **value** (_required_)<br>
+The value to be converted to a YAML string. Can be any valid JSON type (object, array, string, number, etc.)
+
+- **Return Value:** `string`<br>
+Returns the a YAML string containing the serialized value
+
+This method is similar to [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify), except that it converts a value to a YAML string instead of a JSON string.
+
+```javascript
+var YAML = $RefParser.YAML;
+var obj = {
+  title: "person",
+  required: ["name", "age"],
+  properties: {
+    name: {
+      type: "string"
+    },
+    age: {
+      type: "number"
+    }
+  }
+};
+
+
+var string = YAML.stringify(obj);
+
+// title: person
+// required:
+//   - name
+//   - age
+// properties:
+//   name:
+//     type: string
+//   age:
+//     type: number
+```

dist/ref-parser.min.js

@@ -12,6 +12,7 @@ var Promise         = require('./util/promise'),
     ono             = require('ono');
 
 module.exports = $RefParser;
+module.exports.YAML = require('./util/yaml');
 
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,

dist/ref-parser.min.js.map

@@ -1,8 +1,7 @@
 'use strict';
 
-var Promise = require('../util/promise');
-var yaml = require('js-yaml');
-var ono = require('ono');
+var Promise = require('../util/promise'),
+    YAML    = require('../util/yaml');
 
 module.exports = {
   /**
@@ -39,28 +38,14 @@ module.exports = {
    * @returns {Promise}
    */
   parse: function parseYAML(file) {
-    var parsed;
-
     return new Promise(function(resolve, reject) {
       var data = file.data;
       if (Buffer.isBuffer(data)) {
         data = data.toString();
       }
 
       if (typeof data === 'string') {
-        try {
-          parsed = yaml.safeLoad(data);
-        }
-        catch (e) {
-          if (e instanceof Error) {
-            throw e;
-          }
-          else {
-            // https://github.com/nodeca/js-yaml/issues/153
-            throw ono(e, e.message);
-          }
-        }
-        resolve(parsed);
+        resolve(YAML.parse(data));
       }
       else {
         // data is already a JavaScript value (object, array, number, null, NaN, etc.)

docs/README.md

@@ -0,0 +1,56 @@
+/* eslint lines-around-comment: [2, {beforeBlockComment: false}] */
+'use strict';
+
+var yaml = require('js-yaml'),
+    ono  = require('ono');
+
+/**
+ * Simple YAML parsing functions, similar to {@link JSON.parse} and {@link JSON.stringify}
+ */
+module.exports = {
+  /**
+   * Parses a YAML string and returns the value.
+   *
+   * @param {string} text - The YAML string to be parsed
+   * @param {function} [reviver] - Not currently supported. Provided for consistency with {@link JSON.parse}
+   * @returns {*}
+   */
+  parse: function yamlParse(text, reviver) {
+    try {
+      return yaml.safeLoad(text);
+    }
+    catch (e) {
+      if (e instanceof Error) {
+        throw e;
+      }
+      else {
+        // https://github.com/nodeca/js-yaml/issues/153
+        throw ono(e, e.message);
+      }
+    }
+  },
+
+  /**
+   * Converts a JavaScript value to a YAML string.
+   *
+   * @param   {*} value - The value to convert to YAML
+   * @param   {function|array} replacer - Not currently supported. Provided for consistency with {@link JSON.stringify}
+   * @param   {string|number} space - The number of spaces to use for indentation, or a string containing the number of spaces.
+   * @returns {string}
+   */
+  stringify: function yamlStringify(value, replacer, space) {
+    try {
+      var indent = (typeof space === 'string' ? space.length : space) || 2;
+      return yaml.safeDump(value, {indent: indent});
+    }
+    catch (e) {
+      if (e instanceof Error) {
+        throw e;
+      }
+      else {
+        // https://github.com/nodeca/js-yaml/issues/153
+        throw ono(e, e.message);
+      }
+    }
+  }
+};

docs/yaml.md

@@ -0,0 +1,159 @@
+'use strict';
+
+describe('YAML object', function() {
+  describe('parse', function() {
+    it('should parse an object',
+      function(done) {
+        var obj = $RefParser.YAML.parse(
+          'title: person\n' +
+          'required:\n' +
+          '  - name\n' +
+          '  - age\n' +
+          'properties:\n' +
+          '  name:\n' +
+          '    type: string\n' +
+          '  age:\n' +
+          '    type: number'
+        );
+
+        expect(obj).to.deep.equal({
+          title: 'person',
+          required: ['name', 'age'],
+          properties: {
+            name: {
+              type: 'string'
+            },
+            age: {
+              type: 'number'
+            }
+          }
+        });
+        done();
+      }
+    );
+
+    it('should parse a string',
+      function(done) {
+        var str = $RefParser.YAML.parse('hello, world');
+        expect(str).to.equal('hello, world');
+        done();
+      }
+    );
+
+    it('should parse a number',
+      function(done) {
+        var str = $RefParser.YAML.parse('42');
+        expect(str).to.be.a('number').equal(42);
+        done();
+      }
+    );
+  });
+
+  describe('stringify', function() {
+    it('should stringify an object',
+      function(done) {
+        var yaml = $RefParser.YAML.stringify({
+          title: 'person',
+          required: ['name', 'age'],
+          properties: {
+            name: {
+              type: 'string'
+            },
+            age: {
+              type: 'number'
+            }
+          }
+        });
+
+        expect(yaml).to.equal(
+          'title: person\n' +
+          'required:\n' +
+          '  - name\n' +
+          '  - age\n' +
+          'properties:\n' +
+          '  name:\n' +
+          '    type: string\n' +
+          '  age:\n' +
+          '    type: number\n'
+        );
+        done();
+      }
+    );
+
+    it('should support a custom indent (as a string)',
+      function(done) {
+        var yaml = $RefParser.YAML.stringify({
+          title: 'person',
+          required: ['name', 'age'],
+          properties: {
+            name: {
+              type: 'string'
+            },
+            age: {
+              type: 'number'
+            }
+          }
+        }, null, '     ');
+
+        expect(yaml).to.equal(
+          'title: person\n' +
+          'required:\n' +
+          '     - name\n' +
+          '     - age\n' +
+          'properties:\n' +
+          '     name:\n' +
+          '          type: string\n' +
+          '     age:\n' +
+          '          type: number\n'
+        );
+        done();
+      }
+    );
+
+    it('should support a custom indent (as a number)',
+      function(done) {
+        var yaml = $RefParser.YAML.stringify({
+          title: 'person',
+          required: ['name', 'age'],
+          properties: {
+            name: {
+              type: 'string'
+            },
+            age: {
+              type: 'number'
+            }
+          }
+        }, null, 10);
+
+        expect(yaml).to.equal(
+          'title: person\n' +
+          'required:\n' +
+          '          - name\n' +
+          '          - age\n' +
+          'properties:\n' +
+          '          name:\n' +
+          '                    type: string\n' +
+          '          age:\n' +
+          '                    type: number\n'
+        );
+        done();
+      }
+    );
+
+    it('should stringify a string',
+      function(done) {
+        var yaml = $RefParser.YAML.stringify('hello, world');
+        expect(yaml).to.equal('\'hello, world\'\n');
+        done();
+      }
+    );
+
+    it('should stringify a number',
+      function(done) {
+        var yaml = $RefParser.YAML.stringify(42);
+        expect(yaml).to.equal('42\n');
+        done();
+      }
+    );
+  });
+});