New extend function + updates to readme

README.md

@@ -1,4 +1,4 @@
-# Confirge
+# confirge
 
   [![NPM Version][npm-img]][npm-url]
   [![Linux Build][travis-img]][travis-url]
@@ -42,6 +42,45 @@ config = confirge.replace(config,
 });
 ```
 
+## API
+- [confirge()][api-confirge]
+- [confirge.read()][api-confirge-read]
+- [confirge.replace()][api-confirge-replace]
+- [confirge.extend()][api-confirge-extend]
+
+
+### confirge(source)
+Handles a string (file path), function, or object source and returns an object.
+
+#### `source`
+> Type: `string`, `function` or `object`
+
+
+### confirge.read(file)
+Read file and return object. Returns `false` on failure.
+When a function is passed, it is assumed this function returns the path to a file wich should be read.
+
+#### `file`
+> Type: `string` or `function`
+
+
+### confirge.replace(source, vars)
+Loops through all source values and replaces any used variables wich are defined in the vars object.
+
+#### `source`
+> Type: `object` or `array`
+
+#### `vars`
+> Type: `object`
+
+
+### confirge.extend(source...)
+Extend a base object with the given sources. These sources are handled by the main `confirge` function and are only used if objects are returned.
+
+#### `source`
+> Type: `string`, `function` or `object`
+
+
 [npm-img]: https://badge.fury.io/js/confirge.svg
 [npm-url]: https://www.npmjs.com/package/confirge
 [travis-img]: https://img.shields.io/travis/roeldev/confirge/master.svg?label=linux
@@ -52,3 +91,8 @@ config = confirge.replace(config,
 [coveralls-url]: https://coveralls.io/r/roeldev/confirge?branch=master
 [david-img]: https://david-dm.org/roeldev/confirge.svg
 [david-url]: https://david-dm.org/roeldev/confirge
+
+[api-confirge]: #confirge2
+[api-confirge-read]: #1
+[api-confirge-replace]: #2
+[api-confirge-extend]: #3

lib/index.js

@@ -1,6 +1,6 @@
 /**
  * confirge | lib/index.js
- * file version: 0.00.004
+ * file version: 0.00.005
  */
 'use strict';
 
@@ -12,12 +12,24 @@ var _          = require('underscore'),
 
 ////////////////////////////////////////////////////////////////////////////////
 
+/**
+ * Handles a string (file path), function, or object source and returns an
+ * object.
+ *
+ * @param {string|function|object} $source
+ * @return {object|boolean} Returns `false` on failure.
+ */
 var Confirge = function($source)
 {
     var $result = false;
 
+    // assume the string is a file path, read the file
+    if (_.isString($source))
+    {
+        $result = Confirge.read($source);
+    }
     // execute function and return result
-    if (_.isFunction($source))
+    else if (_.isFunction($source))
     {
         $result = Confirge($source());
     }
@@ -26,19 +38,17 @@ var Confirge = function($source)
     {
         $result = $source;
     }
-    else if (_.isString($source))
-    {
-        $result = Confirge.read($source);
-    }
 
     return $result;
 };
 
 /**
- * Read file and return object.
+ * Read file and return object. Returns `false` on failure.
+ * When a function is passed, it is assumed this function returns the path to a
+ * file wich should be read.
  *
- * @param {string} $file - File path to read.
- * @return {object|boolean}
+ * @param {string|function} $file - File path to read.
+ * @return {object|boolean} Returns `false` on failure.
  */
 Confirge.read = function($file)
 {
@@ -62,7 +72,8 @@ Confirge.read = function($file)
 };
 
 /**
- * Replace vars in obj values.
+ * Loops through all source values and replaces any used variables wich are
+ * defined in the vars object.
  *
  * @param {object|array} $source - Object/Array where values are replaced.
  * @param {object} $vars - Vars to replace, { varName: value }.
@@ -85,11 +96,41 @@ Confirge.replace = function($source, $vars)
     return $source;
 };
 
-// copy of deep-extend
-Confirge.extend = DeepExtend;
+/**
+ * Extend a base object with the given sources. These sources are handled by
+ * the main `confirge` function and are only used if objects are returned.
+ *
+ * @param {string|function|object} $source
+ * @return {object|boolean} Returns `false` on failure.
+ */
+Confirge.extend = function($source)
+{
+    var $result  = false,
+        $sources = [];
+
+    for (var $i = 0, $iL = arguments.length; $i < $iL; $i++)
+    {
+        $source = Confirge(arguments[$i]);
+        if ($source !== false)
+        {
+            $sources.push($source);
+        }
+    }
+
+    if ($sources.length === 1)
+    {
+        $result = $sources[0];
+    }
+    else if($sources.length >= 2)
+    {
+        $result = DeepExtend.apply($sources[0], $sources);
+    }
+
+    return $result;
+};
 
 /*
-    Confirge
+    confirge
     Copyright (c) 2015 Roel Schut (roelschut.nl)
 
     This program is free software; you can redistribute it and/or modify