path: added parse() and format() functions

The parse() function splits a path and returns an object

with the different elements. The format() function is the

reverse of this and adds an objects corresponding path

elements to make up a string. nodejs#6976

doc/api/path.markdown

@@ -201,3 +201,47 @@ An example on Windows:
     process.env.PATH.split(path.delimiter)
     // returns
     ['C:\Windows\system32', 'C:\Windows', 'C:\Program Files\nodejs\']
+
+## path.parse
+
+Returns an object from a path string.
+
+An example on *nix:
+
+    path.parse('/home/user/dir/file.txt')
+    // returns
+    {
+        root : "/",
+        dir : "/home/user/dir",
+        base : "file.txt",
+        ext : ".txt",
+        name : "file"
+    }
+
+An example on Windows:
+
+    path.parse('C:\\path\\dir\\index.html')
+    // returns
+    {
+        root : "C:\",
+        dir : "C:\path\dir",
+        base : "index.html",
+        ext : ".html",
+        name : "index"
+    }
+
+## path.format
+
+Returns a path string from an object, the opposite of `path.parse` above.
+
+    path.format({
+        root : "/",
+        dir : "/home/user/dir",
+        base : "file.txt",
+        ext : ".txt",
+        name : "file"
+    })
+    // returns
+    '/home/user/dir/file.txt'
+
+

lib/path.js

@@ -306,6 +306,26 @@ if (isWindows) {
     return outputParts.join('\\');
   };
 
+  // Return all elements
+  exports.parse = function (string) {
+    var allParts = splitPath(string);
+    return {
+      root : allParts[0],
+      dir : allParts[0] +
+        allParts[1].substring(allParts[1].length - 1, allParts[1]),
+      base : allParts[2], ext : allParts[3],
+      name : allParts[2].substring(0, allParts[2].length - allParts[3].length)
+    }
+  }
+
+  // Join and return a parsed path
+  exports.format = function (object) {
+    root = object.root || '';
+    dir = object.dir + this.sep;
+    base = object.base || '';
+    return dir + base;
+  }
+
   exports.sep = '\\';
   exports.delimiter = ';';
 
@@ -444,6 +464,34 @@ if (isWindows) {
     return outputParts.join('/');
   };
 
+  // Return all elements
+  exports.parse = function (string) {
+    var allParts = splitPath(string);
+    return {
+      root : allParts[0],
+      dir : allParts[0] +
+        allParts[1].substring(allParts[1].length - 1, allParts[1]),
+      base : allParts[2], ext : allParts[3],
+      name : allParts[2].substring(0, allParts[2].length - allParts[3].length)
+    }
+  }
+
+  // Join and return a parsed path
+  exports.format = function (object) {
+    root = object.root || '';
+    var sep = this.sep;
+    if (root.match(':') == ':') {
+      sep = '\\';
+    } else if (root === '') {
+      if (object.dir.match(this.sep) == this.sep) {
+        sep = this.sep;
+      }
+    }
+    dir = object.dir + sep;
+    base = object.base || '';
+    return dir + base;
+  }
+
   exports.sep = '/';
   exports.delimiter = ':';
 }

test/simple/test-path-parse-format.js

@@ -0,0 +1,62 @@
+var path = require('../../lib/path');
+
+var winPaths = [
+  'C:\\path\\dir\\index.html',
+  'C:\\another_path\\DIR\\1\\2\\33\\index',
+  'another_path\\DIR with spaces\\1\\2\\33\\index'
+];
+
+var unixPaths = [
+  '/home/user/dir/file.txt',
+  '/home/user/a dir/another File.zip',
+  '/home/user/a dir//another&File.',
+  '/home/user/a$$$dir//another File.zip',
+  'user/dir/another File.zip'
+];
+
+var passCount = 0;
+var paths;
+
+/**
+  * successfully parse Windows paths in Windows and the same for Unix, 
+  * in the same manner that `path` seems to handle things
+  */
+if (require('os').platform() == 'win32') {
+  paths = winPaths;
+} else {
+  paths = unixPaths;
+}
+
+paths.forEach(function(element, index, array) {
+  var count = index + 1;
+  console.log(count + ': `' + element + '`');
+  var output = path.parse(element);
+  var keys = Object.keys(output);
+  var values = [];
+  for (var i = 0; i < Object.keys(output).length; i++) {
+    values.push(output[keys[i]]);
+  }
+  console.log(count + ': [path.parse()] ' + Object.keys(output) + ' => ' + values);
+  console.log(count + ': [path.format()] `' + path.format(path.parse(element)) + '`');
+
+  if (
+
+    /**
+      * check if the re-combined elements in the format() function matches
+      * the original string, and check if each object element matches the
+      * corresponding existing functions in the `path` module
+      */
+    path.format(path.parse(element)) === element &&
+    path.parse(element).dir === path.dirname(element) &&
+    path.parse(element).base === path.basename(element) &&
+    path.parse(element).ext === path.extname(element)
+  ) {
+    console.log('PASSED\n');
+    passCount++;
+  } else {
+    console.log('FAILED\n');
+  }
+  if (count == array.length) {
+    console.log(passCount + ' of ' + count + ' tests passed.');
+  }
+});