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. Fixes #6976.

Fixes: https://github.com/joyent/node/issues/6976
PR-URL: https://github.com/joyent/node/pull/8750
Reviewed-by: Julien Gilli <julien.gilli@joyent.com>

1 files changed, 42 insertions, 0 deletions

diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index 054159533a..3489f1811f 100644
--- a/doc/api/path.markdown
+++ b/doc/api/path.markdown
@@ -202,6 +202,48 @@ An example on Windows:
     // returns
     ['C:\Windows\system32', 'C:\Windows', 'C:\Program Files\nodejs\']
 
+## path.parse(pathString)
+
+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(pathObject)
+
+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'
+
 ## path.posix
 
 Provide access to aforementioned `path` methods but always interact in a posix