Merge pull request #124 from ziadsawalha/feature/98-pass_refs_to_resolvers

#98: Pass $refs to resolvers

Author: JamesMessinger

docs/plugins/resolvers.md

@@ -14,7 +14,7 @@ let myResolver = {
 
   canRead: /^mongodb:/i,
 
-  read(file, callback) {
+  read(file, callback, $refs) {
     MongoClient.connect(file.url, (err, db) => {
       if (err) {
         callback(err);
@@ -55,8 +55,7 @@ let myResolver = {
 };
 ```
 
-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 @@ async function parse (path, $refs, options) {
     };
 
     // Read the file and then parse the data
-    const resolver = await readFile(file, options);
+    const resolver = await readFile(file, options, $refs);
     $ref.pathType = resolver.plugin.name;
     file.data = resolver.result;
 
-    const parser = await parseFile(file, options);
+    const parser = await parseFile(file, options, $refs);
     $ref.value = parser.result;
 
     return parser.result;
@@ -57,7 +57,7 @@ async 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(((resolve, reject) => {
     // console.log('Reading %s', file.url);
 
@@ -67,7 +67,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) {
@@ -95,7 +95,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(((resolve, reject) => {
     // console.log('Parsing %s', file.url);
 
@@ -108,7 +108,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) {
   let plugin, lastError, index = 0;
 
   return new Promise(((resolve, reject) => {
@@ -75,7 +75,7 @@ exports.run = function (plugins, method, file) {
 
       try {
         // console.log('  %s', plugin.name);
-        let result = getResult(plugin, method, file, callback);
+        let 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) {
   let value = obj[prop];
 
   if (typeof value === "function") {
-    return value.apply(obj, [file, callback]);
+    return value.apply(obj, [file, callback, $refs]);
   }
 
   if (!callback) {