feature(URI.joinPath): utility to compose paths from directory tokens, …

…closes #285

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 The release notes tracked in this document are also made available on the [releases page](https://github.com/medialize/URI.js/releases)
 
+### master ###
+
+* adding [`URI.joinPath`](http://medialize.github.io/URI.js/docs.html#static-joinPath) to compose paths from directory tokens - [Issue #285](https://github.com/medialize/URI.js/issues/285)
+
 ### 1.17.1 (February 25th 2016) ###
 
 * fixing [`.normalizePath()`](http://medialize.github.io/URI.js/docs.html#normalize-path) to properly handle percent-encoded dot segments and leading dots in basename - [Issue #264](https://github.com/medialize/URI.js/issues/264), by [JordanMilne](https://github.com/JordanMilne)

docs.html

@@ -121,6 +121,7 @@ <h1><a href="https://github.com/medialize/URI.js">URI.js</a></h1>
             <ul>
                 <li><a href="#relativeto">relativeTo()</a></li>
                 <li><a href="#absoluteto">absoluteTo()</a></li>
+                <li><a href="#static-joinPath">URI.joinPath()</a></li>
             </ul>
         </li>
         <li>
@@ -170,6 +171,8 @@ <h1><a href="https://github.com/medialize/URI.js">URI.js</a></h1>
                 <li><a href="#static-removeQuery">URI.removeQuery()</a></li>
                 <li><a href="#static-commonPath">URI.commonPath()</a></li>
 
+                <li><a href="#static-joinPath">URI.joinPath()</a></li>
+
                 <li><a href="#static-withinString">URI.withinString()</a></li>
 
                 <li><a href="#static-iso8859">URI.iso8859()</a></li>
@@ -1256,7 +1259,24 @@ <h3 id="static-commonPath">URI.commonPath()</h3>
 
 URI.commonPath("/foo", "bar");
 // returns ""</pre>
-
+
+    <h3 id="static-joinPath">URI.joinPath()</h3>
+    <p>URI.joinPath() composes a path from directory tokens.</p>
+    <pre class="prettyprint lang-js">URI.joinPaths('/a/b', '/c', 'd', '/e');
+// returns URI("/a/b/c/d/e")
+
+URI.joinPaths('a/b', 'http://example.com/c', new URI('d/'), '/e');
+// returns URI("a/b/c/d/e")
+
+URI.joinPaths('/a/');
+// returns URI("/a/")
+
+URI.joinPaths('');
+// returns URI("")
+
+URI.joinPaths('', 'a', '');
+// returns URI("/a/")</pre>
+
     <h3 id="static-withinString">URI.withinString()</h3>
     <p>URI.withinString() identifies URIs within text, e.g. to translate them to &lt;a&gt;-Tags. (Obviously you'd want to put the urls inside the href-Attribute and escape them properly…)</p>
     <p class="note">.withinString() only works on plain text, it will not work with HTML!</p>

src/URI.js

@@ -878,6 +878,39 @@
   };
 
 
+  URI.joinPaths = function() {
+    var input = [];
+    var segments = [];
+    var nonEmptySegments = 0;
+
+    for (var i = 0; i < arguments.length; i++) {
+      var url = new URI(arguments[i]);
+      input.push(url);
+      var _segments = url.segment();
+      for (var s = 0; s < _segments.length; s++) {
+        if (typeof _segments[s] === 'string') {
+          segments.push(_segments[s]);
+        }
+
+        if (_segments[s]) {
+          nonEmptySegments++;
+        }
+      }
+    }
+
+    if (!segments.length || !nonEmptySegments) {
+      return new URI('');
+    }
+
+    var uri = new URI('').segment(segments);
+
+    if (input[0].path() === '' || input[0].path().slice(0, 1) === '/') {
+      uri.path('/' + uri.path());
+    }
+
+    return uri.normalize();
+  };
+
   URI.commonPath = function(one, two) {
     var length = Math.min(one.length, two.length);
     var pos;

test/test.js

@@ -1651,6 +1651,36 @@
     window.IPv6         = actual.IPv6;
     window.SecondLevelDomains = actual.SecondLevelDomains;
   });
+  test('joinPaths', function() {
+    var result;
+
+    result = URI.joinPaths('/a/b', '/c', 'd', '/e').toString();
+    equal(result, '/a/b/c/d/e', 'absolute paths');
+
+    result = URI.joinPaths('a/b', 'http://example.com/c', new URI('d/'), '/e').toString();
+    equal(result, 'a/b/c/d/e', 'relative path');
+
+    result = URI.joinPaths('/a/').toString();
+    equal(result, '/a/', 'single absolute directory');
+
+    result = URI.joinPaths('/a').toString();
+    equal(result, '/a', 'single absolute segment');
+
+    result = URI.joinPaths('a').toString();
+    equal(result, 'a', 'single relative segment');
+
+    result = URI.joinPaths('').toString();
+    equal(result, '', 'empty string');
+
+    result = URI.joinPaths().toString();
+    equal(result, '', 'no argument');
+
+    result = URI.joinPaths('', 'a', '', '', 'b').toString();
+    equal(result, '/a/b', 'leading empty segment');
+
+    result = URI.joinPaths('a', '', '', 'b', '', '').toString();
+    equal(result, 'a/b/', 'trailing empty segment');
+  });
 
   module('comparing URLs');
   test('equals', function() {