path: allow calling platform specific methods

Add path.posix and path.win32 which have the specific methods like
resolve and normalize so you can specifically normalize or resolve
based on the target platform.

PR-URL: https://github.com/joyent/node/pull/5661
Reviewed-by: Chris Dickinson <christopher.s.dickinson@gmail.com>

doc/api/path.markdown

@@ -201,3 +201,13 @@ An example on Windows:
     process.env.PATH.split(path.delimiter)
     // returns
     ['C:\Windows\system32', 'C:\Windows', 'C:\Program Files\nodejs\']
+
+## path.posix
+
+Provide access to aforementioned `path` methods but always interact in a posix
+compatible way.
+
+## path.win32
+
+Provide access to aforementioned `path` methods but always interact in a win32
+compatible way.

lib/path.js

@@ -55,7 +55,6 @@ function normalizeArray(parts, allowAboveRoot) {
 }
 
 
-if (isWindows) {
 // Regex to split a windows path into three parts: [*, device, slash,
 // tail] windows-only
 var splitDeviceRe =
@@ -65,9 +64,10 @@ if (isWindows) {
 var splitTailRe =
     /^([\s\S]*?)((?:\.{1,2}|[^\\\/]+?|)(\.[^.\/\\]*|))(?:[\\\/]*)$/;
 
+var win32 = {};
+
 // Function to split a filename into [root, dir, basename, ext]
-  // windows version
+win32.splitPath = function(filename) {
-  var splitPath = function(filename) {
   // Separate device+slash from tail
   var result = splitDeviceRe.exec(filename),
       device = (result[1] || '') + (result[2] || ''),
@@ -85,8 +85,7 @@ if (isWindows) {
 };
 
 // path.resolve([from ...], to)
-  // windows version
+win32.resolve = function() {
-  exports.resolve = function() {
   var resolvedDevice = '',
       resolvedTail = '',
       resolvedAbsolute = false;
@@ -121,7 +120,7 @@ if (isWindows) {
     var result = splitDeviceRe.exec(path),
         device = result[1] || '',
         isUnc = device && device.charAt(1) !== ':',
-          isAbsolute = exports.isAbsolute(path),
+        isAbsolute = win32.isAbsolute(path),
         tail = result[3];
 
     if (device &&
@@ -173,12 +172,12 @@ if (isWindows) {
          '.';
 };
 
-  // windows version
+
-  exports.normalize = function(path) {
+win32.normalize = function(path) {
   var result = splitDeviceRe.exec(path),
       device = result[1] || '',
       isUnc = device && device.charAt(1) !== ':',
-        isAbsolute = exports.isAbsolute(path),
+      isAbsolute = win32.isAbsolute(path),
       tail = result[3],
       trailingSlash = /[\\\/]$/.test(tail);
 
@@ -208,8 +207,8 @@ if (isWindows) {
   return device + (isAbsolute ? '\\' : '') + tail;
 };
 
-  // windows version
+
-  exports.isAbsolute = function(path) {
+win32.isAbsolute = function(path) {
   var result = splitDeviceRe.exec(path),
       device = result[1] || '',
       isUnc = !!device && device.charAt(1) !== ':';
@@ -217,8 +216,7 @@ if (isWindows) {
   return !!result[2] || isUnc;
 };
 
-  // windows version
+win32.join = function() {
-  exports.join = function() {
   function f(p) {
     if (!util.isString(p)) {
       throw new TypeError('Arguments to path.join must be strings');
@@ -246,18 +244,18 @@ if (isWindows) {
     joined = joined.replace(/^[\\\/]{2,}/, '\\');
   }
 
-    return exports.normalize(joined);
+  return win32.normalize(joined);
 };
 
+
 // path.relative(from, to)
 // it will solve the relative path from 'from' to 'to', for instance:
 // from = 'C:\\orandea\\test\\aaa'
 // to = 'C:\\orandea\\impl\\bbb'
 // The output of the function should be: '..\\..\\impl\\bbb'
-  // windows version
+win32.relative = function(from, to) {
-  exports.relative = function(from, to) {
+  from = win32.resolve(from);
-    from = exports.resolve(from);
+  to = win32.resolve(to);
-    to = exports.resolve(to);
 
   // windows is not case sensitive
   var lowerFrom = from.toLowerCase();
@@ -306,22 +304,85 @@ if (isWindows) {
   return outputParts.join('\\');
 };
 
-  exports.sep = '\\';
-  exports.delimiter = ';';
 
-} else /* posix */ {
+win32._makeLong = function(path) {
+  // Note: this will *probably* throw somewhere.
+  if (!util.isString(path))
+    return path;
+
+  if (!path) {
+    return '';
+  }
+
+  var resolvedPath = win32.resolve(path);
+
+  if (/^[a-zA-Z]\:\\/.test(resolvedPath)) {
+    // path is local filesystem path, which needs to be converted
+    // to long UNC path.
+    return '\\\\?\\' + resolvedPath;
+  } else if (/^\\\\[^?.]/.test(resolvedPath)) {
+    // path is network UNC path, which needs to be converted
+    // to long UNC path.
+    return '\\\\?\\UNC\\' + resolvedPath.substring(2);
+  }
+
+  return path;
+};
+
+
+win32.dirname = function(path) {
+  var result = win32.splitPath(path),
+      root = result[0],
+      dir = result[1];
+
+  if (!root && !dir) {
+    // No dirname whatsoever
+    return '.';
+  }
+
+  if (dir) {
+    // It has a dirname, strip trailing slash
+    dir = dir.substr(0, dir.length - 1);
+  }
+
+  return root + dir;
+};
+
+
+win32.basename = function(path, ext) {
+  var f = win32.splitPath(path)[2];
+  // TODO: make this comparison case-insensitive on windows?
+  if (ext && f.substr(-1 * ext.length) === ext) {
+    f = f.substr(0, f.length - ext.length);
+  }
+  return f;
+};
+
+
+win32.extname = function(path) {
+  return win32.splitPath(path)[3];
+};
+
+
+win32.sep = '\\';
+win32.delimiter = ';';
+
 
 // Split a filename into [root, dir, basename, ext], unix version
 // 'root' is just a slash, or nothing.
 var splitPathRe =
     /^(\/?|)([\s\S]*?)((?:\.{1,2}|[^\/]+?|)(\.[^.\/]*|))(?:[\/]*)$/;
-  var splitPath = function(filename) {
+var posix = {};
+
+
+posix.splitPath = function(filename) {
   return splitPathRe.exec(filename).slice(1);
 };
 
+
 // path.resolve([from ...], to)
 // posix version
-  exports.resolve = function() {
+posix.resolve = function() {
   var resolvedPath = '',
       resolvedAbsolute = false;
 
@@ -352,9 +413,9 @@ if (isWindows) {
 
 // path.normalize(path)
 // posix version
-  exports.normalize = function(path) {
+posix.normalize = function(path) {
-    var isAbsolute = exports.isAbsolute(path),
+  var isAbsolute = posix.isAbsolute(path),
-        trailingSlash = path[path.length - 1] === '/',
+      trailingSlash = path.substr(-1) === '/',
       segments = path.split('/'),
       nonEmptySegments = [];
 
@@ -377,12 +438,12 @@ if (isWindows) {
 };
 
 // posix version
-  exports.isAbsolute = function(path) {
+posix.isAbsolute = function(path) {
   return path.charAt(0) === '/';
 };
 
 // posix version
-  exports.join = function() {
+posix.join = function() {
   var path = '';
   for (var i = 0; i < arguments.length; i++) {
     var segment = arguments[i];
@@ -397,15 +458,15 @@ if (isWindows) {
       }
     }
   }
-    return exports.normalize(path);
+  return posix.normalize(path);
 };
 
 
 // path.relative(from, to)
 // posix version
-  exports.relative = function(from, to) {
+posix.relative = function(from, to) {
-    from = exports.resolve(from).substr(1);
+  from = posix.resolve(from).substr(1);
-    to = exports.resolve(to).substr(1);
+  to = posix.resolve(to).substr(1);
 
   function trim(arr) {
     var start = 0;
@@ -444,12 +505,14 @@ if (isWindows) {
   return outputParts.join('/');
 };
 
-  exports.sep = '/';
-  exports.delimiter = ':';
-}
 
-exports.dirname = function(path) {
+posix._makeLong = function(path) {
-  var result = splitPath(path),
+  return path;
+};
+
+
+posix.dirname = function(path) {
+  var result = posix.splitPath(path),
       root = result[0],
       dir = result[1];
 
@@ -467,8 +530,8 @@ exports.dirname = function(path) {
 };
 
 
-exports.basename = function(path, ext) {
+posix.basename = function(path, ext) {
-  var f = splitPath(path)[2];
+  var f = posix.splitPath(path)[2];
   // TODO: make this comparison case-insensitive on windows?
   if (ext && f.substr(-1 * ext.length) === ext) {
     f = f.substr(0, f.length - ext.length);
@@ -477,47 +540,19 @@ exports.basename = function(path, ext) {
 };
 
 
-exports.extname = function(path) {
+posix.extname = function(path) {
-  return splitPath(path)[3];
+  return posix.splitPath(path)[3];
 };
 
 
-exports.exists = util.deprecate(function(path, callback) {
+posix.sep = '/';
-  require('fs').exists(path, callback);
+posix.delimiter = ':';
-}, 'path.exists is now called `fs.exists`.');
 
 
-exports.existsSync = util.deprecate(function(path) {
+if (isWindows)
-  return require('fs').existsSync(path);
+  module.exports = win32;
-}, 'path.existsSync is now called `fs.existsSync`.');
+else /* posix */
+  module.exports = posix;
 
-
+module.exports.posix = posix;
-if (isWindows) {
+module.exports.win32 = win32;
-  exports._makeLong = function(path) {
-    // Note: this will *probably* throw somewhere.
-    if (!util.isString(path))
-      return path;
-
-    if (!path) {
-      return '';
-    }
-
-    var resolvedPath = exports.resolve(path);
-
-    if (/^[a-zA-Z]\:\\/.test(resolvedPath)) {
-      // path is local filesystem path, which needs to be converted
-      // to long UNC path.
-      return '\\\\?\\' + resolvedPath;
-    } else if (/^\\\\[^?.]/.test(resolvedPath)) {
-      // path is network UNC path, which needs to be converted
-      // to long UNC path.
-      return '\\\\?\\UNC\\' + resolvedPath.substring(2);
-    }
-
-    return path;
-  };
-} else {
-  exports._makeLong = function(path) {
-    return path;
-  };
-}

test/simple/test-path.js

@@ -37,22 +37,19 @@ assert.equal(path.basename('basename.ext'), 'basename.ext');
 assert.equal(path.basename('basename.ext/'), 'basename.ext');
 assert.equal(path.basename('basename.ext//'), 'basename.ext');
 
-if (isWindows) {
 // On Windows a backslash acts as a path separator.
-  assert.equal(path.basename('\\dir\\basename.ext'), 'basename.ext');
+assert.equal(path.win32.basename('\\dir\\basename.ext'), 'basename.ext');
-  assert.equal(path.basename('\\basename.ext'), 'basename.ext');
+assert.equal(path.win32.basename('\\basename.ext'), 'basename.ext');
-  assert.equal(path.basename('basename.ext'), 'basename.ext');
+assert.equal(path.win32.basename('basename.ext'), 'basename.ext');
-  assert.equal(path.basename('basename.ext\\'), 'basename.ext');
+assert.equal(path.win32.basename('basename.ext\\'), 'basename.ext');
-  assert.equal(path.basename('basename.ext\\\\'), 'basename.ext');
+assert.equal(path.win32.basename('basename.ext\\\\'), 'basename.ext');
 
-} else {
 // On unix a backslash is just treated as any other character.
-  assert.equal(path.basename('\\dir\\basename.ext'), '\\dir\\basename.ext');
+assert.equal(path.posix.basename('\\dir\\basename.ext'), '\\dir\\basename.ext');
-  assert.equal(path.basename('\\basename.ext'), '\\basename.ext');
+assert.equal(path.posix.basename('\\basename.ext'), '\\basename.ext');
-  assert.equal(path.basename('basename.ext'), 'basename.ext');
+assert.equal(path.posix.basename('basename.ext'), 'basename.ext');
-  assert.equal(path.basename('basename.ext\\'), 'basename.ext\\');
+assert.equal(path.posix.basename('basename.ext\\'), 'basename.ext\\');
-  assert.equal(path.basename('basename.ext\\\\'), 'basename.ext\\\\');
+assert.equal(path.posix.basename('basename.ext\\\\'), 'basename.ext\\\\');
-}
 
 // POSIX filenames may include control characters
 // c.f. http://www.dwheeler.com/essays/fixing-unix-linux-filenames.html
@@ -73,35 +70,33 @@ assert.equal(path.dirname(''), '.');
 assert.equal(path.dirname('/'), '/');
 assert.equal(path.dirname('////'), '/');
 
-if (isWindows) {
+assert.equal(path.win32.dirname('c:\\'), 'c:\\');
-  assert.equal(path.dirname('c:\\'), 'c:\\');
+assert.equal(path.win32.dirname('c:\\foo'), 'c:\\');
-  assert.equal(path.dirname('c:\\foo'), 'c:\\');
+assert.equal(path.win32.dirname('c:\\foo\\'), 'c:\\');
-  assert.equal(path.dirname('c:\\foo\\'), 'c:\\');
+assert.equal(path.win32.dirname('c:\\foo\\bar'), 'c:\\foo');
-  assert.equal(path.dirname('c:\\foo\\bar'), 'c:\\foo');
+assert.equal(path.win32.dirname('c:\\foo\\bar\\'), 'c:\\foo');
-  assert.equal(path.dirname('c:\\foo\\bar\\'), 'c:\\foo');
+assert.equal(path.win32.dirname('c:\\foo\\bar\\baz'), 'c:\\foo\\bar');
-  assert.equal(path.dirname('c:\\foo\\bar\\baz'), 'c:\\foo\\bar');
+assert.equal(path.win32.dirname('\\'), '\\');
-  assert.equal(path.dirname('\\'), '\\');
+assert.equal(path.win32.dirname('\\foo'), '\\');
-  assert.equal(path.dirname('\\foo'), '\\');
+assert.equal(path.win32.dirname('\\foo\\'), '\\');
-  assert.equal(path.dirname('\\foo\\'), '\\');
+assert.equal(path.win32.dirname('\\foo\\bar'), '\\foo');
-  assert.equal(path.dirname('\\foo\\bar'), '\\foo');
+assert.equal(path.win32.dirname('\\foo\\bar\\'), '\\foo');
-  assert.equal(path.dirname('\\foo\\bar\\'), '\\foo');
+assert.equal(path.win32.dirname('\\foo\\bar\\baz'), '\\foo\\bar');
-  assert.equal(path.dirname('\\foo\\bar\\baz'), '\\foo\\bar');
+assert.equal(path.win32.dirname('c:'), 'c:');
-  assert.equal(path.dirname('c:'), 'c:');
+assert.equal(path.win32.dirname('c:foo'), 'c:');
-  assert.equal(path.dirname('c:foo'), 'c:');
+assert.equal(path.win32.dirname('c:foo\\'), 'c:');
-  assert.equal(path.dirname('c:foo\\'), 'c:');
+assert.equal(path.win32.dirname('c:foo\\bar'), 'c:foo');
-  assert.equal(path.dirname('c:foo\\bar'), 'c:foo');
+assert.equal(path.win32.dirname('c:foo\\bar\\'), 'c:foo');
-  assert.equal(path.dirname('c:foo\\bar\\'), 'c:foo');
+assert.equal(path.win32.dirname('c:foo\\bar\\baz'), 'c:foo\\bar');
-  assert.equal(path.dirname('c:foo\\bar\\baz'), 'c:foo\\bar');
+assert.equal(path.win32.dirname('\\\\unc\\share'), '\\\\unc\\share');
-  assert.equal(path.dirname('\\\\unc\\share'), '\\\\unc\\share');
+assert.equal(path.win32.dirname('\\\\unc\\share\\foo'), '\\\\unc\\share\\');
-  assert.equal(path.dirname('\\\\unc\\share\\foo'), '\\\\unc\\share\\');
+assert.equal(path.win32.dirname('\\\\unc\\share\\foo\\'), '\\\\unc\\share\\');
-  assert.equal(path.dirname('\\\\unc\\share\\foo\\'), '\\\\unc\\share\\');
+assert.equal(path.win32.dirname('\\\\unc\\share\\foo\\bar'),
-  assert.equal(path.dirname('\\\\unc\\share\\foo\\bar'),
              '\\\\unc\\share\\foo');
-  assert.equal(path.dirname('\\\\unc\\share\\foo\\bar\\'),
+assert.equal(path.win32.dirname('\\\\unc\\share\\foo\\bar\\'),
              '\\\\unc\\share\\foo');
-  assert.equal(path.dirname('\\\\unc\\share\\foo\\bar\\baz'),
+assert.equal(path.win32.dirname('\\\\unc\\share\\foo\\bar\\baz'),
              '\\\\unc\\share\\foo\\bar');
-}
 
 
 assert.equal(path.extname(''), '');
@@ -146,28 +141,25 @@ assert.equal(path.extname('file//'), '');
 assert.equal(path.extname('file./'), '.');
 assert.equal(path.extname('file.//'), '.');
 
-if (isWindows) {
 // On windows, backspace is a path separator.
-  assert.equal(path.extname('.\\'), '');
+assert.equal(path.win32.extname('.\\'), '');
-  assert.equal(path.extname('..\\'), '');
+assert.equal(path.win32.extname('..\\'), '');
-  assert.equal(path.extname('file.ext\\'), '.ext');
+assert.equal(path.win32.extname('file.ext\\'), '.ext');
-  assert.equal(path.extname('file.ext\\\\'), '.ext');
+assert.equal(path.win32.extname('file.ext\\\\'), '.ext');
-  assert.equal(path.extname('file\\'), '');
+assert.equal(path.win32.extname('file\\'), '');
-  assert.equal(path.extname('file\\\\'), '');
+assert.equal(path.win32.extname('file\\\\'), '');
-  assert.equal(path.extname('file.\\'), '.');
+assert.equal(path.win32.extname('file.\\'), '.');
-  assert.equal(path.extname('file.\\\\'), '.');
+assert.equal(path.win32.extname('file.\\\\'), '.');
 
-} else {
 // On unix, backspace is a valid name component like any other character.
-  assert.equal(path.extname('.\\'), '');
+assert.equal(path.posix.extname('.\\'), '');
-  assert.equal(path.extname('..\\'), '.\\');
+assert.equal(path.posix.extname('..\\'), '.\\');
-  assert.equal(path.extname('file.ext\\'), '.ext\\');
+assert.equal(path.posix.extname('file.ext\\'), '.ext\\');
-  assert.equal(path.extname('file.ext\\\\'), '.ext\\\\');
+assert.equal(path.posix.extname('file.ext\\\\'), '.ext\\\\');
-  assert.equal(path.extname('file\\'), '');
+assert.equal(path.posix.extname('file\\'), '');
-  assert.equal(path.extname('file\\\\'), '');
+assert.equal(path.posix.extname('file\\\\'), '');
-  assert.equal(path.extname('file.\\'), '.\\');
+assert.equal(path.posix.extname('file.\\'), '.\\');
-  assert.equal(path.extname('file.\\\\'), '.\\\\');
+assert.equal(path.posix.extname('file.\\\\'), '.\\\\');
-}
 
 // path.join tests
 var failures = [];
@@ -294,23 +286,21 @@ joinThrowTests.forEach(function(test) {
 
 
 // path normalize tests
-if (isWindows) {
+assert.equal(path.win32.normalize('./fixtures///b/../b/c.js'),
-  assert.equal(path.normalize('./fixtures///b/../b/c.js'),
              'fixtures\\b\\c.js');
-  assert.equal(path.normalize('/foo/../../../bar'), '\\bar');
+assert.equal(path.win32.normalize('/foo/../../../bar'), '\\bar');
-  assert.equal(path.normalize('a//b//../b'), 'a\\b');
+assert.equal(path.win32.normalize('a//b//../b'), 'a\\b');
-  assert.equal(path.normalize('a//b//./c'), 'a\\b\\c');
+assert.equal(path.win32.normalize('a//b//./c'), 'a\\b\\c');
-  assert.equal(path.normalize('a//b//.'), 'a\\b');
+assert.equal(path.win32.normalize('a//b//.'), 'a\\b');
-  assert.equal(path.normalize('//server/share/dir/file.ext'),
+assert.equal(path.win32.normalize('//server/share/dir/file.ext'),
              '\\\\server\\share\\dir\\file.ext');
-} else {
+
-  assert.equal(path.normalize('./fixtures///b/../b/c.js'),
+assert.equal(path.posix.normalize('./fixtures///b/../b/c.js'),
              'fixtures/b/c.js');
-  assert.equal(path.normalize('/foo/../../../bar'), '/bar');
+assert.equal(path.posix.normalize('/foo/../../../bar'), '/bar');
-  assert.equal(path.normalize('a//b//../b'), 'a/b');
+assert.equal(path.posix.normalize('a//b//../b'), 'a/b');
-  assert.equal(path.normalize('a//b//./c'), 'a/b/c');
+assert.equal(path.posix.normalize('a//b//./c'), 'a/b/c');
-  assert.equal(path.normalize('a//b//.'), 'a/b');
+assert.equal(path.posix.normalize('a//b//.'), 'a/b');
-}
 
 // path.resolve tests
 if (isWindows) {
@@ -352,21 +342,19 @@ resolveTests.forEach(function(test) {
 assert.equal(failures.length, 0, failures.join(''));
 
 // path.isAbsolute tests
-if (isWindows) {
+assert.equal(path.win32.isAbsolute('//server/file'), true);
-  assert.equal(path.isAbsolute('//server/file'), true);
+assert.equal(path.win32.isAbsolute('\\\\server\\file'), true);
-  assert.equal(path.isAbsolute('\\\\server\\file'), true);
+assert.equal(path.win32.isAbsolute('C:/Users/'), true);
-  assert.equal(path.isAbsolute('C:/Users/'), true);
+assert.equal(path.win32.isAbsolute('C:\\Users\\'), true);
-  assert.equal(path.isAbsolute('C:\\Users\\'), true);
+assert.equal(path.win32.isAbsolute('C:cwd/another'), false);
-  assert.equal(path.isAbsolute('C:cwd/another'), false);
+assert.equal(path.win32.isAbsolute('C:cwd\\another'), false);
-  assert.equal(path.isAbsolute('C:cwd\\another'), false);
+assert.equal(path.win32.isAbsolute('directory/directory'), false);
-  assert.equal(path.isAbsolute('directory/directory'), false);
+assert.equal(path.win32.isAbsolute('directory\\directory'), false);
-  assert.equal(path.isAbsolute('directory\\directory'), false);
+
-} else {
+assert.equal(path.posix.isAbsolute('/home/foo'), true);
-  assert.equal(path.isAbsolute('/home/foo'), true);
+assert.equal(path.posix.isAbsolute('/home/foo/..'), true);
-  assert.equal(path.isAbsolute('/home/foo/..'), true);
+assert.equal(path.posix.isAbsolute('bar/'), false);
-  assert.equal(path.isAbsolute('bar/'), false);
+assert.equal(path.posix.isAbsolute('./baz'), false);
-  assert.equal(path.isAbsolute('./baz'), false);
-}
 
 // path.relative tests
 if (isWindows) {
@@ -405,20 +393,20 @@ relativeTests.forEach(function(test) {
 });
 assert.equal(failures.length, 0, failures.join(''));
 
-// path.sep tests
-if (isWindows) {
 // windows
-  assert.equal(path.sep, '\\');
+assert.equal(path.win32.sep, '\\');
-} else {
 // posix
-  assert.equal(path.sep, '/');
+assert.equal(path.posix.sep, '/');
-}
 
 // path.delimiter tests
-if (isWindows) {
 // windows
-  assert.equal(path.delimiter, ';');
+assert.equal(path.win32.delimiter, ';');
-} else {
+
 // posix
-  assert.equal(path.delimiter, ':');
+assert.equal(path.posix.delimiter, ':');
-}
+
+
+if (isWindows)
+  assert.deepEqual(path, path.win32, 'should be win32 path module');
+else
+  assert.deepEqual(path, path.posix, 'should be posix path module');