diff --git a/doc/api/path.markdown b/doc/api/path.markdown index 7a06ec68f2df1d..454c79353f7b3c 100644 --- a/doc/api/path.markdown +++ b/doc/api/path.markdown @@ -8,86 +8,92 @@ The file system is not consulted to check whether paths are valid. Use `require('path')` to use this module. The following methods are provided: -## path.normalize(p) - -Normalize a string path, taking care of `'..'` and `'.'` parts. +## path.basename(p[, ext]) -When multiple slashes are found, they're replaced by a single one; -when the path contains a trailing slash, it is preserved. -On Windows backslashes are used. +Return the last portion of a path. Similar to the Unix `basename` command. Example: - path.normalize('/foo/bar//baz/asdf/quux/..') + path.basename('/foo/bar/baz/asdf/quux.html') // returns - '/foo/bar/baz/asdf' + 'quux.html' -*Note:* If the path string passed as argument is a zero-length string then `'.'` - will be returned, which represents the current working directory. + path.basename('/foo/bar/baz/asdf/quux.html', '.html') + // returns + 'quux' -## path.join([path1][, path2][, ...]) +## path.delimiter -Join all arguments together and normalize the resulting path. +The platform-specific path delimiter, `;` or `':'`. -Arguments must be strings. In v0.8, non-string arguments were -silently ignored. In v0.10 and up, an exception is thrown. +An example on *nix: -Example: + console.log(process.env.PATH) + // '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin' - path.join('/foo', 'bar', 'baz/asdf', 'quux', '..') + process.env.PATH.split(path.delimiter) // returns - '/foo/bar/baz/asdf' + ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin'] - path.join('foo', {}, 'bar') - // throws exception - TypeError: Arguments to path.join must be strings +An example on Windows: -*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. + console.log(process.env.PATH) + // 'C:\Windows\system32;C:\Windows;C:\Program Files\node\' -## path.resolve([from ...], to) + process.env.PATH.split(path.delimiter) + // returns + ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\'] -Resolves `to` to an absolute path. +## path.dirname(p) -If `to` isn't already absolute `from` arguments are prepended in right to left -order, until an absolute path is found. If after using all `from` paths still -no absolute path is found, the current working directory is used as well. The -resulting path is normalized, and trailing slashes are removed unless the path -gets resolved to the root directory. Non-string `from` arguments are ignored. +Return the directory name of a path. Similar to the Unix `dirname` command. -Another way to think of it is as a sequence of `cd` commands in a shell. +Example: - path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile') + path.dirname('/foo/bar/baz/asdf/quux') + // returns + '/foo/bar/baz/asdf' -Is similar to: +## path.extname(p) - cd foo/bar - cd /tmp/file/ - cd .. - cd a/../subfile - pwd +Return the extension of the path, from the last '.' to end of string +in the last portion of the path. If there is no '.' in the last portion +of the path or the first character of it is '.', then it returns +an empty string. Examples: -The difference is that the different paths don't need to exist and may also be -files. + path.extname('index.html') + // returns + '.html' -Examples: + path.extname('index.coffee.md') + // returns + '.md' - path.resolve('/foo/bar', './baz') + path.extname('index.') // returns - '/foo/bar/baz' + '.' - path.resolve('/foo/bar', '/tmp/file/') + path.extname('index') // returns - '/tmp/file' + '' - path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif') - // if currently in /home/myself/node, it returns - '/home/myself/node/wwwroot/static_files/gif/image.gif' + path.extname('.index') + // returns + '' -*Note:* If the arguments to `resolve` have zero-length strings then the current - working directory will be used instead of them. +## 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.isAbsolute(path) @@ -112,165 +118,159 @@ Windows examples: 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`. +## path.join([path1][, path2][, ...]) -At times we have two absolute paths, and we need to derive the relative -path from one to the other. This is actually the reverse transform of -`path.resolve`, which means we see that: +Join all arguments together and normalize the resulting path. - path.resolve(from, path.relative(from, to)) == path.resolve(to) +Arguments must be strings. In v0.8, non-string arguments were +silently ignored. In v0.10 and up, an exception is thrown. -Examples: +Example: - path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb') + path.join('/foo', 'bar', 'baz/asdf', 'quux', '..') // returns - '..\\..\\impl\\bbb' + '/foo/bar/baz/asdf' - path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb') - // returns - '../../impl/bbb' + path.join('foo', {}, 'bar') + // throws exception + TypeError: Arguments to path.join must be strings -*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. +*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.dirname(p) +## path.normalize(p) -Return the directory name of a path. Similar to the Unix `dirname` command. +Normalize a string path, taking care of `'..'` and `'.'` parts. + +When multiple slashes are found, they're replaced by a single one; +when the path contains a trailing slash, it is preserved. +On Windows backslashes are used. Example: - path.dirname('/foo/bar/baz/asdf/quux') + path.normalize('/foo/bar//baz/asdf/quux/..') // returns '/foo/bar/baz/asdf' -## path.basename(p[, ext]) +*Note:* If the path string passed as argument is a zero-length string then `'.'` + will be returned, which represents the current working directory. -Return the last portion of a path. Similar to the Unix `basename` command. +## path.parse(pathString) -Example: +Returns an object from a path string. - path.basename('/foo/bar/baz/asdf/quux.html') - // returns - 'quux.html' +An example on *nix: - path.basename('/foo/bar/baz/asdf/quux.html', '.html') + path.parse('/home/user/dir/file.txt') // returns - 'quux' - -## path.extname(p) + { + root : "/", + dir : "/home/user/dir", + base : "file.txt", + ext : ".txt", + name : "file" + } -Return the extension of the path, from the last '.' to end of string -in the last portion of the path. If there is no '.' in the last portion -of the path or the first character of it is '.', then it returns -an empty string. Examples: +An example on Windows: - path.extname('index.html') + path.parse('C:\\path\\dir\\index.html') // returns - '.html' + { + root : "C:\\", + dir : "C:\\path\\dir", + base : "index.html", + ext : ".html", + name : "index" + } - path.extname('index.coffee.md') - // returns - '.md' +## path.posix - path.extname('index.') - // returns - '.' +Provide access to aforementioned `path` methods but always interact in a posix +compatible way. - path.extname('index') - // returns - '' +## path.relative(from, to) - path.extname('.index') - // returns - '' +Solve the relative path from `from` to `to`. -## path.sep +At times we have two absolute paths, and we need to derive the relative +path from one to the other. This is actually the reverse transform of +`path.resolve`, which means we see that: -The platform-specific file separator. `'\\'` or `'/'`. + path.resolve(from, path.relative(from, to)) == path.resolve(to) -An example on *nix: +Examples: - 'foo/bar/baz'.split(path.sep) + path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb') // returns - ['foo', 'bar', 'baz'] - -An example on Windows: + '..\\..\\impl\\bbb' - 'foo\\bar\\baz'.split(path.sep) + path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb') // returns - ['foo', 'bar', 'baz'] + '../../impl/bbb' -## path.delimiter +*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. -The platform-specific path delimiter, `;` or `':'`. +## path.resolve([from ...], to) -An example on *nix: +Resolves `to` to an absolute path. - console.log(process.env.PATH) - // '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin' +If `to` isn't already absolute `from` arguments are prepended in right to left +order, until an absolute path is found. If after using all `from` paths still +no absolute path is found, the current working directory is used as well. The +resulting path is normalized, and trailing slashes are removed unless the path +gets resolved to the root directory. Non-string `from` arguments are ignored. - process.env.PATH.split(path.delimiter) - // returns - ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin'] +Another way to think of it is as a sequence of `cd` commands in a shell. -An example on Windows: + path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile') - console.log(process.env.PATH) - // 'C:\Windows\system32;C:\Windows;C:\Program Files\node\' +Is similar to: - process.env.PATH.split(path.delimiter) - // returns - ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\'] + cd foo/bar + cd /tmp/file/ + cd .. + cd a/../subfile + pwd -## path.parse(pathString) +The difference is that the different paths don't need to exist and may also be +files. -Returns an object from a path string. +Examples: -An example on *nix: + path.resolve('/foo/bar', './baz') + // returns + '/foo/bar/baz' - path.parse('/home/user/dir/file.txt') + path.resolve('/foo/bar', '/tmp/file/') // returns - { - root : "/", - dir : "/home/user/dir", - base : "file.txt", - ext : ".txt", - name : "file" - } + '/tmp/file' -An example on Windows: + path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif') + // if currently in /home/myself/node, it returns + '/home/myself/node/wwwroot/static_files/gif/image.gif' - path.parse('C:\\path\\dir\\index.html') - // returns - { - root : "C:\\", - dir : "C:\\path\\dir", - base : "index.html", - ext : ".html", - name : "index" - } +*Note:* If the arguments to `resolve` have zero-length strings then the current + working directory will be used instead of them. -## path.format(pathObject) +## path.sep -Returns a path string from an object, the opposite of `path.parse` above. +The platform-specific file separator. `'\\'` or `'/'`. - path.format({ - root : "/", - dir : "/home/user/dir", - base : "file.txt", - ext : ".txt", - name : "file" - }) +An example on *nix: + + 'foo/bar/baz'.split(path.sep) // returns - '/home/user/dir/file.txt' + ['foo', 'bar', 'baz'] -## path.posix +An example on Windows: -Provide access to aforementioned `path` methods but always interact in a posix -compatible way. + 'foo\\bar\\baz'.split(path.sep) + // returns + ['foo', 'bar', 'baz'] ## path.win32