Pass $refs to resolvers (#98)

This allows resolvers to understand more of
the context around what they are resolving.

Ex. `$refs._root$Ref.path` indicates
the file being dereferenced.

Author: ziadsawalha

docs/plugins/resolvers.md

@@ -14,7 +14,7 @@ var myResolver = {
 
   canRead: /^mongodb:/i,
 
-  read: function(file, callback) {
+  read: function(file, callback, $refs) {
     MongoClient.connect(file.url, function(err, db) {
       if (err) {
         callback(err);
@@ -53,8 +53,7 @@ canRead: function(file) {
 }
 ```
 
-When using the function form, the `file` parameter is a [file info object](file-info-object.md), which contains information about the file being resolved.
-
+When using the function form, the `file` parameter is a [file info object](file-info-object.md), which contains information about the file being resolved. The `$refs` parameter is a [`$Refs`](../refs.md) object, which allows your resolver to determine context (ex. `$refs._root$Ref.path` can be used to determine the relative path your resolver is operating from).
 
 #### The `read` method
 This is where the real work of a resolver happens.  The `read` method accepts the same [file info object](file-info-object.md) as the `canRead` function, but rather than returning a boolean value, the `read` method should return the contents of the file.  The file contents should be returned in as raw a form as possible, such as a string or a byte array.  Any further parsing or processing should be done by [parsers](parsers.md).

lib/parse.js

@@ -32,11 +32,11 @@ function parse (path, $refs, options) {
     };
 
     // Read the file and then parse the data
-    return readFile(file, options)
+    return readFile(file, options, $refs)
       .then(function (resolver) {
         $ref.pathType = resolver.plugin.name;
         file.data = resolver.result;
-        return parseFile(file, options);
+        return parseFile(file, options, $refs);
       })
       .then(function (parser) {
         $ref.value = parser.result;
@@ -59,7 +59,7 @@ function parse (path, $refs, options) {
  * @returns {Promise}
  * The promise resolves with the raw file contents and the resolver that was used.
  */
-function readFile (file, options) {
+function readFile (file, options, $refs) {
   return new Promise(function (resolve, reject) {
     // console.log('Reading %s', file.url);
 
@@ -69,7 +69,7 @@ function readFile (file, options) {
 
     // Run the resolvers, in order, until one of them succeeds
     plugins.sort(resolvers);
-    plugins.run(resolvers, "read", file)
+    plugins.run(resolvers, "read", file, $refs)
       .then(resolve, onError);
 
     function onError (err) {
@@ -97,7 +97,7 @@ function readFile (file, options) {
  * @returns {Promise}
  * The promise resolves with the parsed file contents and the parser that was used.
  */
-function parseFile (file, options) {
+function parseFile (file, options, $refs) {
   return new Promise(function (resolve, reject) {
     // console.log('Parsing %s', file.url);
 
@@ -110,7 +110,7 @@ function parseFile (file, options) {
 
     // Run the parsers, in order, until one of them succeeds
     plugins.sort(parsers);
-    plugins.run(parsers, "parse", file)
+    plugins.run(parsers, "parse", file, $refs)
       .then(onParsed, onError);
 
     function onParsed (parser) {

lib/util/plugins.js

@@ -60,7 +60,7 @@ exports.sort = function (plugins) {
  * @param {object}    file    - A file info object, which will be passed to each method
  * @returns {Promise}
  */
-exports.run = function (plugins, method, file) {
+exports.run = function (plugins, method, file, $refs) {
   var plugin, lastError, index = 0;
 
   return new Promise(function (resolve, reject) {
@@ -75,7 +75,7 @@ exports.run = function (plugins, method, file) {
 
       try {
         // console.log('  %s', plugin.name);
-        var result = getResult(plugin, method, file, callback);
+        var result = getResult(plugin, method, file, callback, $refs);
         if (result && typeof result.then === "function") {
           // A promise was returned
           result.then(onSuccess, onError);
@@ -128,11 +128,11 @@ exports.run = function (plugins, method, file) {
  * @param   {function} [callback] - A callback function, which will be passed to the method
  * @returns {*}
  */
-function getResult (obj, prop, file, callback) {
+function getResult (obj, prop, file, callback, $refs) {
   var value = obj[prop];
 
   if (typeof value === "function") {
-    return value.apply(obj, [file, callback]);
+    return value.apply(obj, [file, callback, $refs]);
   }
 
   if (!callback) {