feat(join): add a utility for joining paths

This commit adds a utility function for joining two paths together. It
differentiates itself from the normalize function because normalize
produces a path relative to a base file location.

This commit also adds an acknowledgements document recognizing the
source of the various bathing algorithms.

ACKNOWLEDGEMENTS.md

@@ -0,0 +1,30 @@
+# Acknowledgements
+
+The `normalize` function in this library was adapted from the internals of [http://requirejs.org/](http://requirejs.org/). Much thanks goes to the authors who worked out this algorithm. Below is the required notice from the original library.
+
+Also, the `join` function comes from [this gist](https://gist.github.com/creationix/7435851).
+
+---
+
+MIT License
+-----------
+
+Copyright (c) 2010-2014, The Dojo Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

gulpfile.js

@@ -11,7 +11,7 @@ var pkg = require('./package.json');
 var fs = require('fs');
 
 var path = {
-  source:'lib/**/*.js',
+  source:'src/**/*.js',
   output:'dist/',
   doc:'./doc'
 };

karma.conf.js

@@ -14,7 +14,7 @@ module.exports = function(config) {
 
     jspm: {
       // Edit this to your needs
-      loadFiles: ['lib/**/*.js', 'test/**/*.js']
+      loadFiles: ['src/**/*.js', 'test/**/*.js']
     },
 
 
@@ -31,7 +31,7 @@ module.exports = function(config) {
     // available preprocessors: https://npmjs.org/browse/keyword/karma-preprocessor
     preprocessors: {
       'test/**/*.js': ['6to5'],
-      'lib/**/*.js': ['6to5']
+      'src/**/*.js': ['6to5']
     },
 
 

lib/index.js → src/index.js

@@ -1,3 +1,26 @@
+function trimDots(ary) {
+  var i, part;
+  for (i = 0; i < ary.length; i++) {
+      part = ary[i];
+      if (part === '.') {
+          ary.splice(i, 1);
+          i -= 1;
+      } else if (part === '..') {
+          // If at the start, or previous value is still ..,
+          // keep them so that when converted to a path it may
+          // still work when converted to a path, even though
+          // as an ID it is less than ideal. In larger point
+          // releases, may be better to just kick out an error.
+          if (i === 0 || (i == 1 && ary[2] === '..') || ary[i - 1] === '..') {
+              continue;
+          } else if (i > 0) {
+              ary.splice(i - 1, 2);
+              i -= 2;
+          }
+      }
+  }
+}
+
 export function normalize(name, baseName){
   var lastIndex,
       normalizedBaseParts,
@@ -21,25 +44,29 @@ export function normalize(name, baseName){
   return name.join('/');
 }
 
-function trimDots(ary) {
-  var i, part;
-  for (i = 0; i < ary.length; i++) {
-      part = ary[i];
-      if (part === '.') {
-          ary.splice(i, 1);
-          i -= 1;
-      } else if (part === '..') {
-          // If at the start, or previous value is still ..,
-          // keep them so that when converted to a path it may
-          // still work when converted to a path, even though
-          // as an ID it is less than ideal. In larger point
-          // releases, may be better to just kick out an error.
-          if (i === 0 || (i == 1 && ary[2] === '..') || ary[i - 1] === '..') {
-              continue;
-          } else if (i > 0) {
-              ary.splice(i - 1, 2);
-              i -= 2;
-          }
-      }
+// Joins path segments.  Preserves initial "/" and resolves ".." and "."
+// Does not support using ".." to go above/outside the root.
+// This means that join("foo", "../../bar") will not resolve to "../bar"
+export function join(/* path segments */) {
+  // Split the inputs into a list of path commands.
+  var parts = [];
+  for (var i = 0, l = arguments.length; i < l; i++) {
+    parts = parts.concat(arguments[i].split("/"));
+  }
+  // Interpret the path commands to get the new resolved path.
+  var newParts = [];
+  for (i = 0, l = parts.length; i < l; i++) {
+    var part = parts[i];
+    // Remove leading and trailing slashes
+    // Also remove "." segments
+    if (!part || part === ".") continue;
+    // Interpret ".." to pop the last segment
+    if (part === "..") newParts.pop();
+    // Push new path segments.
+    else newParts.push(part);
   }
+  // Preserve the initial slash if there was one.
+  if (parts[0] === "") newParts.unshift("");
+  // Turn back into a single string path.
+  return newParts.join("/") || (newParts.length ? "/" : ".");
 }

test/path.spec.js

@@ -1,10 +1,19 @@
-import { normalize } from '../lib/index';
+import { normalize, join } from '../src/index';
 
 describe('normalize', () => {
-  it('can normalize a path with a baseUrl', () => {
-    var baseUrl = 'http://durandal.io/';
-    var path = './my/module';
+  it('can make a path relative to a file', () => {
+    var baseUrl = 'some/file.html';
+    var path = './other/module';
 
-    expect(normalize(path, baseUrl)).toBe('http://durandal.io/my/module');
+    expect(normalize(path, baseUrl)).toBe('some/other/module');
+  });
+});
+
+describe('join', () => {
+  it('can join two paths', () => {
+    var path1 = 'one';
+    var path2 = 'two';
+
+    expect(join(path1, path2)).toBe('one/two');
   });
 });