Skip to content

Commit

Permalink
doc: Adding note about empty strings in path module
Browse files Browse the repository at this point in the history
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.join('')
    '.'
    > 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.
  • Loading branch information
thefourtheye committed Jul 6, 2015
1 parent fb05c8e commit 63874da
Showing 1 changed file with 16 additions and 1 deletion.
17 changes: 16 additions & 1 deletion doc/api/path.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,9 @@ Example:
// returns
'/foo/bar/baz/asdf'

*Note:* If the path is a zero-length string then the current working directory
will be returned.

## path.join([path1][, path2][, ...])

Join all arguments together and normalize the resulting path.
Expand All @@ -39,6 +42,9 @@ Example:
// throws exception
TypeError: Arguments to path.join must be strings

*Note:* If the joined path is a zero-length string then the current working
directory will be returned.

## path.resolve([from ...], to)

Resolves `to` to an absolute path.
Expand Down Expand Up @@ -78,6 +84,9 @@ Examples:
// if currently in /home/myself/iojs, it returns
'/home/myself/iojs/wwwroot/static_files/gif/image.gif'

*Note:* If the path is a zero-length string then the current working directory
will be used.

## path.isAbsolute(path)

Determines whether `path` is an absolute path. An absolute path will always
Expand All @@ -94,9 +103,11 @@ 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 is a zero-length string then `false` will be returned.

## path.relative(from, to)

Solve the relative path from `from` to `to`.
Expand All @@ -117,6 +128,10 @@ Examples:
// returns
'../../impl/bbb'

*Note:* If any of the paths passed are zero-length strings then the current
working directory will be used instead. 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.
Expand Down

0 comments on commit 63874da

Please sign in to comment.