From 65963ec26f8bcb9ef287aa7ddd40e8ecc734d991 Mon Sep 17 00:00:00 2001
From: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Date: Sun, 5 Jul 2015 15:08:16 +0000
Subject: [PATCH] doc,test: empty strings in path module

The path module's `join, normalize, isAbsolute, relative and resolve`
functions return/use the current directory if they are passed zero
length strings.

    > process.version
    'v2.3.4-pre'
    > path.win32.join('')
    '.'
    > path.posix.join('')
    '.'
    > path.win32.normalize('')
    '.'
    > path.posix.normalize('')
    '.'
    > path.win32.isAbsolute('')
    false
    > path.posix.isAbsolute('')
    false
    > path.win32.relative('', '')
    ''
    > path.posix.relative('', '')
    ''
    > path.win32relative('.', '')
    ''
    > path.posix.relative('.', '')
    ''
    > path.posix.resolve('')
    '/home/thefourtheye/Desktop'
    > path.win32.resolve('')
    '\\home\\thefourtheye\\Desktop'

Since empty paths are not valid in any of the operating systems people
normally use, this behaviour might be a surprise to the users. This
commit introduces "Notes" about this, wherever applicable in `path`'s
documentation.

The tests makes sure that the behaviour is intact between
commits.

PR-URL: https://github.com/nodejs/io.js/pull/2106
Reviewed-By: Rich Trott <rtrott@gmail.com>
---
 doc/api/path.markdown                         | 21 ++++++++++-
 .../parallel/test-path-zero-length-strings.js | 35 +++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 test/parallel/test-path-zero-length-strings.js

diff --git a/doc/api/path.markdown b/doc/api/path.markdown
index 08495a79e5399c..7177ab4d2d0b99 100644
--- a/doc/api/path.markdown
+++ b/doc/api/path.markdown
@@ -22,6 +22,9 @@ Example:
     // returns
     '/foo/bar/baz/asdf'
 
+*Note:* If the path string passed as argument is a zero-length string then `'.'`
+        will be returned, which represents the current working directory.
+
 ## path.join([path1][, path2][, ...])
 
 Join all arguments together and normalize the resulting path.
@@ -39,6 +42,11 @@ Example:
     // throws exception
     TypeError: Arguments to path.join must be strings
 
+*Note:* If the arguments to `join` have zero-length strings, unlike other path
+        module functions, they will be ignored. If the joined path string is a
+        zero-length string then `'.'` will be returned, which represents the
+        current working directory.
+
 ## path.resolve([from ...], to)
 
 Resolves `to` to an absolute path.
@@ -78,6 +86,9 @@ Examples:
     // if currently in /home/myself/iojs, it returns
     '/home/myself/iojs/wwwroot/static_files/gif/image.gif'
 
+*Note:* If the arguments to `resolve` have zero-length strings then the current
+        working directory will be used instead of them.
+
 ## path.isAbsolute(path)
 
 Determines whether `path` is an absolute path. An absolute path will always
@@ -94,9 +105,13 @@ Windows examples:
 
     path.isAbsolute('//server')  // true
     path.isAbsolute('C:/foo/..') // true
-    path.isAbsolute('bar\\baz')   // false
+    path.isAbsolute('bar\\baz')  // false
     path.isAbsolute('.')         // false
 
+*Note:* If the path string passed as parameter is a zero-length string, unlike
+        other path module functions, it will be used as-is and `false` will be
+        returned.
+
 ## path.relative(from, to)
 
 Solve the relative path from `from` to `to`.
@@ -117,6 +132,10 @@ Examples:
     // returns
     '../../impl/bbb'
 
+*Note:* If the arguments to `relative` have zero-length strings then the current
+        working directory will be used instead of the zero-length strings. If
+        both the paths are the same then a zero-length string will be returned.
+
 ## path.dirname(p)
 
 Return the directory name of a path.  Similar to the Unix `dirname` command.
diff --git a/test/parallel/test-path-zero-length-strings.js b/test/parallel/test-path-zero-length-strings.js
new file mode 100644
index 00000000000000..09d5e947e4a9df
--- /dev/null
+++ b/test/parallel/test-path-zero-length-strings.js
@@ -0,0 +1,35 @@
+'use strict';
+
+// These testcases are specific to one uncommon behaviour in path module. Few
+// of the functions in path module, treat '' strings as current working
+// directory. This test makes sure that the behaviour is intact between commits.
+// See: https://github.com/nodejs/io.js/pull/2106
+
+const common = require('../common');
+const assert = require('assert');
+const path = require('path');
+const pwd = process.cwd();
+
+// join will internally ignore all the zero-length strings and it will return
+// '.' if the joined string is a zero-length string.
+assert.equal(path.join(''), '.');
+assert.equal(path.join('', ''), '.');
+assert.equal(path.join(pwd), pwd);
+assert.equal(path.join(pwd, ''), pwd);
+
+// normalize will return '.' if the input is a zero-length string
+assert.equal(path.normalize(''), '.');
+assert.equal(path.normalize(pwd), pwd);
+
+// Since '' is not a valid path in any of the common environments, return false
+assert.equal(path.isAbsolute(''), false);
+
+// resolve, internally ignores all the zero-length strings and returns the
+// current working directory
+assert.equal(path.resolve(''), pwd);
+assert.equal(path.resolve('', ''), pwd);
+
+// relative, internally calls resolve. So, '' is actually the current directory
+assert.equal(path.relative('', pwd), '');
+assert.equal(path.relative(pwd, ''), '');
+assert.equal(path.relative(pwd, pwd), '');