Checking in my current progress on #8

Not fully done yet, but pretty close.

Author: JamesMessinger

dist/ref-parser.js

@@ -54,7 +54,7 @@ The difference is that in the second example you now have a reference to `parser
 
 
 ### Callbacks vs. Promises
-Many people prefer [ES6 Promise syntax](http://javascriptplayground.com/blog/2015/02/promises/) instead of callbacks.  JSON Schema $Ref Parser allows you to use whichever one you prefer.  
+Many people prefer [ES6 Promise syntax](http://javascriptplayground.com/blog/2015/02/promises/) instead of callbacks.  JSON Schema $Ref Parser allows you to use whichever one you prefer.
 
 If you pass a callback function to any method, then the method will call the callback using the Node.js error-first convention.  If you do _not_ pass a callback function, then the method will return an ES6 Promise.
 
@@ -87,7 +87,7 @@ $RefParser.dereference(mySchema)
 ### Circular $Refs
 JSON Schema files can contain [circular $ref pointers](https://gist.github.com/BigstickCarpet/d18278935fc73e3a0ee1), and JSON Schema $Ref Parser fully supports them. Circular references can be resolved and dereferenced just like any other reference.  However, if you intend to serialize the dereferenced schema as JSON, then you should be aware that [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) does not support circular references by default, so you will need to [use a custom replacer function](https://stackoverflow.com/questions/11616630/json-stringify-avoid-typeerror-converting-circular-structure-to-json).
 
-You can disable circular references by setting the [`$refs.circular`](options.md) option to `false`. Then, if a circular reference is found, a `ReferenceError` will be thrown.
+You can disable circular references by setting the [`dereference.circular`](options.md) option to `false`. Then, if a circular reference is found, a `ReferenceError` will be thrown.
 
 Another option is to use the [`bundle`](ref-parser.md#bundleschema-options-callback) method rather than the [`dereference`](ref-parser.md#dereferenceschema-options-callback) method.  Bundling does _not_ result in circular references, because it simply converts _external_ `$ref` pointers to _internal_ ones.
 

dist/ref-parser.js.map

@@ -15,8 +15,8 @@ This object is a map of JSON References and their resolved values.  It also has
 - [`isExpired()`](#isexpiredref)
 - [`expire()`](#expireref)
 - [`exists()`](#existsref)
-- [`get()`](#getref-options)
-- [`set()`](#setref-value-options)
+- [`get()`](#getref)
+- [`set()`](#setref-value)
 
 
 ### `circular`
@@ -138,14 +138,11 @@ $RefParser.resolve("my-schema.json")
 ```
 
 
-### `get($ref, [options])`
+### `get($ref)`
 
 - **$ref** (_required_) - `string`<br>
 The JSON Reference path, optionally with a JSON Pointer in the hash
 
-- **options** (_optional_) - `object`<br>
-See [options](options.md) for the full list of options
-
 - **Return Value:** `boolean`<br>
 Gets the value at the given path in the schema. Throws an error if the path does not exist.
 
@@ -157,17 +154,14 @@ $RefParser.resolve("my-schema.json")
 ```
 
 
-### `set($ref, value, [options])`
+### `set($ref, value)`
 
 - **$ref** (_required_) - `string`<br>
 The JSON Reference path, optionally with a JSON Pointer in the hash
 
 - **value** (_required_)<br>
 The value to assign. Can be anything (object, string, number, etc.)
 
-- **options** (_optional_) - `object`<br>
-See [options](options.md) for the full list of options
-
 Sets the value at the given path in the schema. If the property, or any of its parents, don't exist, they will be created.
 
 ```javascript

dist/ref-parser.min.js

@@ -86,7 +86,7 @@ function crawl(obj, path, pathFromRoot, inventory, $refs, options) {
 function inventory$Ref($refParent, $refKey, path, pathFromRoot, inventory, $refs, options) {
   var $ref = $refParent[$refKey];
   var $refPath = url.resolve(path, $ref.$ref);
-  var pointer = $refs._resolve($refPath, options);
+  var pointer = $refs._resolve($refPath);
   var depth = Pointer.parse(pathFromRoot).length;
   var file = util.path.stripHash(pointer.path);
   var hash = util.path.getHash(pointer.path);

dist/ref-parser.min.js.map

@@ -44,7 +44,7 @@ function crawl(obj, path, pathFromRoot, parents, $refs, options) {
       var value = obj[key];
       var circular = false;
 
-      if ($Ref.isAllowed$Ref(value, options)) {
+      if ($Ref.is$Ref(value, options)) {
         var dereferenced = dereference$Ref(value, keyPath, keyPathFromRoot, parents, $refs, options);
         circular = dereferenced.circular;
         obj[key] = dereferenced.value;
@@ -82,7 +82,7 @@ function dereference$Ref($ref, path, pathFromRoot, parents, $refs, options) {
   util.debug('Dereferencing $ref pointer "%s" at %s', $ref.$ref, path);
 
   var $refPath = url.resolve(path, $ref.$ref);
-  var pointer = $refs._resolve($refPath, options);
+  var pointer = $refs._resolve($refPath);
 
   // Check for circular references
   var directCircular = pointer.circular;
@@ -98,7 +98,7 @@ function dereference$Ref($ref, path, pathFromRoot, parents, $refs, options) {
     circular = crawl(dereferencedValue, pointer.path, pathFromRoot, parents, $refs, options);
   }
 
-  if (circular && !directCircular && options.$refs.circular === 'ignore') {
+  if (circular && !directCircular && options.dereference.circular === 'ignore') {
     // The user has chosen to "ignore" circular references, so don't change the value
     dereferencedValue = $ref;
   }
@@ -117,7 +117,7 @@ function dereference$Ref($ref, path, pathFromRoot, parents, $refs, options) {
 
 /**
  * Called when a circular reference is found.
- * It sets the {@link $Refs#circular} flag, and throws an error if options.$refs.circular is false.
+ * It sets the {@link $Refs#circular} flag, and throws an error if options.dereference.circular is false.
  *
  * @param {string} keyPath - The JSON Reference path of the circular reference
  * @param {$Refs} $refs
@@ -126,7 +126,7 @@ function dereference$Ref($ref, path, pathFromRoot, parents, $refs, options) {
  */
 function foundCircularReference(keyPath, $refs, options) {
   $refs.circular = true;
-  if (!options.$refs.circular) {
+  if (!options.dereference.circular) {
     throw ono.reference('Circular $ref pointer found at %s', keyPath);
   }
   return true;

docs/README.md

@@ -1,6 +1,6 @@
 'use strict';
 
-var Promise     = require('./promise'),
+var Promise     = require('./util/promise'),
     Options     = require('./options'),
     $Refs       = require('./refs'),
     $Ref        = require('./ref'),
@@ -14,7 +14,7 @@ var Promise     = require('./promise'),
     ono         = require('ono');
 
 module.exports = $RefParser;
-module.exports.YAML = require('./yaml');
+module.exports.YAML = require('./util/yaml');
 
 /**
  * This class parses a JSON schema, builds a map of its JSON references and their resolved values,
@@ -72,7 +72,8 @@ $RefParser.prototype.parse = function(schema, options, callback) {
     this.schema = args.schema;
     this.$refs._basePath = '';
     var $ref = new $Ref(this.$refs, this.$refs._basePath);
-    $ref.setValue(this.schema, args.options);
+    $ref.value = this.schema;
+    $ref.setExpiration(options);
 
     return maybe(args.callback, Promise.resolve(this.schema));
   }
@@ -93,7 +94,7 @@ $RefParser.prototype.parse = function(schema, options, callback) {
   return read(args.schema, this.$refs, args.options)
     .then(function(result) {
       var value = result.$ref.value;
-      if (!value || typeof value !== 'object' || value instanceof Buffer) {
+      if (!value || typeof value !== 'object' || Buffer.isBuffer(value)) {
         throw ono.syntax('"%s" is not a valid JSON Schema', me.$refs._basePath);
       }
       else {

docs/refs.md

@@ -1,6 +1,13 @@
 /* eslint lines-around-comment: [2, {beforeBlockComment: false}] */
 'use strict';
 
+var parseJSON   = require('./parse/json'),
+    parseYAML   = require('./parse/yaml'),
+    parseText   = require('./parse/text'),
+    parseBinary = require('./parse/binary'),
+    readFile    = require('./read/file'),
+    readHttp    = require('./read/http');
+
 module.exports = $RefParserOptions;
 
 /**
@@ -11,143 +18,91 @@ module.exports = $RefParserOptions;
  */
 function $RefParserOptions(options) {
   /**
-   * Determines what types of files can be parsed
+   * Determines how different types of files will be parsed.
+   *
+   * You can add additional parsers of your own, replace an existing one with
+   * your own implemenation, or disable any parser by setting it to false.
+   *
+   * Each of the built-in parsers has the following options:
+   *
+   *  order   {number}    - The order in which the parsers will run
+   *
+   *  ext     {string[]}  - An array of file extensions and/or RegExp patterns.
+   *                        Only matching files will be parsed by this parser.
+   *
+   *  empty   {boolean}   - Whether to allow "empty" files. Enabled by default.
+   *                        "Empty" includes zero-byte files, as well as JSON/YAML files that
+   *                        don't contain any keys.
    */
-  this.allow = {
-    /**
-     * Are JSON files allowed?
-     * If false, then all schemas must be in YAML format.
-     * @type {boolean}
-     */
-    json: true,
-
-    /**
-     * Are YAML files allowed?
-     * If false, then all schemas must be in JSON format.
-     * @type {boolean}
-     */
-    yaml: true,
-
-    /**
-     * Are zero-byte files allowed?
-     * If false, then an error will be thrown if a file is empty.
-     * @type {boolean}
-     */
-    empty: true,
+  this.parse = {
+    json: parseJSON,
+    yaml: parseYAML,
+    text: parseText,
+    binary: parseBinary,
+  };
 
-    /**
-     * Can unknown file types be $referenced?
-     * If true, then they will be parsed as Buffers (byte arrays).
-     * If false, then an error will be thrown.
-     * @type {boolean}
-     */
-    unknown: true
+  /**
+   * Determines how external JSON References will be resolved.
+   *
+   * You can add additional readers of your own, replace an existing one with
+   * your own implemenation, or disable any reader by setting it to false.
+   *
+   * Each of the built-in readers has the following options:
+   *
+   *  order   {number}    - The order in which the reader will run
+   *
+   *  cache   {number}    - How long to cache files (in milliseconds)
+   *                        The default cache duration is different for each reader.
+   *                        Setting the cache duration to zero disables caching for that reader.
+   *
+   * The HTTP reader has additional options.  See read/http.js for details.
+   */
+  this.resolve = {
+    file: readFile,
+    http: readHttp,
   };
 
   /**
    * Determines the types of JSON references that are allowed.
    */
-  this.$refs = {
-    /**
-     * Allow JSON references to other parts of the same file?
-     * @type {boolean}
-     */
-    internal: true,
-
-    /**
-     * Allow JSON references to external files/URLs?
-     * @type {boolean}
-     */
-    external: true,
-
+  this.dereference = {
     /**
-     * Allow circular (recursive) JSON references?
+     * Dereference circular (recursive) JSON references?
      * If false, then a {@link ReferenceError} will be thrown if a circular reference is found.
      * If "ignore", then circular references will not be dereferenced.
+     *
      * @type {boolean|string}
      */
     circular: true
   };
 
-  /**
-   * How long to cache files (in seconds).
-   */
-  this.cache = {
-    /**
-     * How long to cache local files, in seconds.
-     * @type {number}
-     */
-    fs: 60, // 1 minute
-
-    /**
-     * How long to cache files downloaded via HTTP, in seconds.
-     * @type {number}
-     */
-    http: 5 * 60, // 5 minutes
-
-    /**
-     * How long to cache files downloaded via HTTPS, in seconds.
-     * @type {number}
-     */
-    https: 5 * 60 // 5 minutes
-  };
-
-  /**
-   * HTTP request options
-   */
-  this.http = {
-    /**
-     * HTTP headers to send when downloading files.
-     */
-    headers: {},
-
-    /**
-     * HTTP request timeout (in milliseconds).
-     */
-    timeout: 5000,
-
-    /**
-     * The maximum number of HTTP redirects to follow.
-     * To disable automatic following of redirects, set this to zero.
-     */
-    redirects: 5,
-
-    /**
-     * The `withCredentials` option of XMLHttpRequest.
-     * Set this to `true` if you're downloading files from a CORS-enabled server that requires authentication
-     */
-    withCredentials: false,
-
-  };
-
   merge(options, this);
 }
 
 /**
- * Fast, two-level object merge.
+ * Merges user-specified options with default options.
  *
- * @param {?object} src - The object to merge into dest
- * @param {object} dest - The object to be modified
+ * @param {?object} user - The options that were specified by the user
+ * @param {$RefParserOptions} defaults - The {@link $RefParserOptions} object that we're populating
+ * @returns {*}
  */
-function merge(src, dest) {
-  if (src) {
-    var topKeys = Object.keys(src);
-    for (var i = 0; i < topKeys.length; i++) {
-      var topKey = topKeys[i];
-      var srcChild = src[topKey];
-      if (dest[topKey] === undefined) {
-        dest[topKey] = srcChild;
+function merge(user, defaults) {
+  if (user) {
+    var keys = Object.keys(user);
+    for (var i = 0; i < keys.length; i++) {
+      var key = keys[i];
+      var userSetting = user[key];
+      var defaultSetting = defaults[key];
+
+      if (userSetting && typeof userSetting === 'object' && !Array.isArray(userSetting)) {
+        // An object with nested options, so merge it too
+        defaults[key] = merge(userSetting, defaultSetting);
       }
       else {
-        var childKeys = Object.keys(srcChild);
-        for (var j = 0; j < childKeys.length; j++) {
-          var childKey = childKeys[j];
-          var srcChildValue = srcChild[childKey];
-          if (srcChildValue !== undefined) {
-            dest[topKey][childKey] = srcChildValue;
-          }
-        }
+        // A scalar value, function, or array. So override the default value.
+        defaults[key] = userSetting;
       }
     }
   }
+  return defaults;
 }