doc/api/path.markdown

   1 # Path
   2
   3     Stability: 2 - Stable
   4
   5 This module contains utilities for handling and transforming file
   6 paths.  Almost all these methods perform only string transformations.
   7 The file system is not consulted to check whether paths are valid.
   8
   9 Use `require('path')` to use this module.  The following methods are provided:
  10
  11 ## path.basename(p[, ext])
  12
  13 Return the last portion of a path.  Similar to the Unix `basename` command.
  14
  15 Example:
  16
  17     path.basename('/foo/bar/baz/asdf/quux.html')
  18     // returns
  19     'quux.html'
  20
  21     path.basename('/foo/bar/baz/asdf/quux.html', '.html')
  22     // returns
  23     'quux'
  24
  25 ## path.delimiter
  26
  27 The platform-specific path delimiter, `;` or `':'`.
  28
  29 An example on \*nix:
  30
  31     console.log(process.env.PATH)
  32     // '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'
  33
  34     process.env.PATH.split(path.delimiter)
  35     // returns
  36     ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']
  37
  38 An example on Windows:
  39
  40     console.log(process.env.PATH)
  41     // 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'
  42
  43     process.env.PATH.split(path.delimiter)
  44     // returns
  45     ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']
  46
  47 ## path.dirname(p)
  48
  49 Return the directory name of a path.  Similar to the Unix `dirname` command.
  50
  51 Example:
  52
  53     path.dirname('/foo/bar/baz/asdf/quux')
  54     // returns
  55     '/foo/bar/baz/asdf'
  56
  57 ## path.extname(p)
  58
  59 Return the extension of the path, from the last '.' to end of string
  60 in the last portion of the path.  If there is no '.' in the last portion
  61 of the path or the first character of it is '.', then it returns
  62 an empty string.  Examples:
  63
  64     path.extname('index.html')
  65     // returns
  66     '.html'
  67
  68     path.extname('index.coffee.md')
  69     // returns
  70     '.md'
  71
  72     path.extname('index.')
  73     // returns
  74     '.'
  75
  76     path.extname('index')
  77     // returns
  78     ''
  79
  80     path.extname('.index')
  81     // returns
  82     ''
  83
  84 ## path.format(pathObject)
  85
  86 Returns a path string from an object, the opposite of [`path.parse`][].
  87
  88     path.format({
  89         root : "/",
  90         dir : "/home/user/dir",
  91         base : "file.txt",
  92         ext : ".txt",
  93         name : "file"
  94     })
  95     // returns
  96     '/home/user/dir/file.txt'
  97
  98 ## path.isAbsolute(path)
  99
 100 Determines whether `path` is an absolute path. An absolute path will always
 101 resolve to the same location, regardless of the working directory.
 102
 103 Posix examples:
 104
 105     path.isAbsolute('/foo/bar') // true
 106     path.isAbsolute('/baz/..')  // true
 107     path.isAbsolute('qux/')     // false
 108     path.isAbsolute('.')        // false
 109
 110 Windows examples:
 111
 112     path.isAbsolute('//server')  // true
 113     path.isAbsolute('C:/foo/..') // true
 114     path.isAbsolute('bar\\baz')  // false
 115     path.isAbsolute('.')         // false
 116
 117 *Note:* If the path string passed as parameter is a zero-length string, unlike
 118         other path module functions, it will be used as-is and `false` will be
 119         returned.
 120
 121 ## path.join([path1][, path2][, ...])
 122
 123 Join all arguments together and normalize the resulting path.
 124
 125 Arguments must be strings.  In v0.8, non-string arguments were
 126 silently ignored.  In v0.10 and up, an exception is thrown.
 127
 128 Example:
 129
 130     path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
 131     // returns
 132     '/foo/bar/baz/asdf'
 133
 134     path.join('foo', {}, 'bar')
 135     // throws exception
 136     TypeError: Arguments to path.join must be strings
 137
 138 *Note:* If the arguments to `join` have zero-length strings, unlike other path
 139         module functions, they will be ignored. If the joined path string is a
 140         zero-length string then `'.'` will be returned, which represents the
 141         current working directory.
 142
 143 ## path.normalize(p)
 144
 145 Normalize a string path, taking care of `'..'` and `'.'` parts.
 146
 147 When multiple slashes are found, they're replaced by a single one;
 148 when the path contains a trailing slash, it is preserved.
 149 On Windows backslashes are used.
 150
 151 Example:
 152
 153     path.normalize('/foo/bar//baz/asdf/quux/..')
 154     // returns
 155     '/foo/bar/baz/asdf'
 156
 157 *Note:* If the path string passed as argument is a zero-length string then `'.'`
 158         will be returned, which represents the current working directory.
 159
 160 ## path.parse(pathString)
 161
 162 Returns an object from a path string.
 163
 164 An example on \*nix:
 165
 166     path.parse('/home/user/dir/file.txt')
 167     // returns
 168     {
 169         root : "/",
 170         dir : "/home/user/dir",
 171         base : "file.txt",
 172         ext : ".txt",
 173         name : "file"
 174     }
 175
 176 An example on Windows:
 177
 178     path.parse('C:\\path\\dir\\index.html')
 179     // returns
 180     {
 181         root : "C:\\",
 182         dir : "C:\\path\\dir",
 183         base : "index.html",
 184         ext : ".html",
 185         name : "index"
 186     }
 187
 188 ## path.posix
 189
 190 Provide access to aforementioned `path` methods but always interact in a posix
 191 compatible way.
 192
 193 ## path.relative(from, to)
 194
 195 Solve the relative path from `from` to `to`.
 196
 197 At times we have two absolute paths, and we need to derive the relative
 198 path from one to the other.  This is actually the reverse transform of
 199 `path.resolve`, which means we see that:
 200
 201     path.resolve(from, path.relative(from, to)) == path.resolve(to)
 202
 203 Examples:
 204
 205     path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
 206     // returns
 207     '..\\..\\impl\\bbb'
 208
 209     path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
 210     // returns
 211     '../../impl/bbb'
 212
 213 *Note:* If the arguments to `relative` have zero-length strings then the current
 214         working directory will be used instead of the zero-length strings. If
 215         both the paths are the same then a zero-length string will be returned.
 216
 217 ## path.resolve([from ...], to)
 218
 219 Resolves `to` to an absolute path.
 220
 221 If `to` isn't already absolute `from` arguments are prepended in right to left
 222 order, until an absolute path is found. If after using all `from` paths still
 223 no absolute path is found, the current working directory is used as well. The
 224 resulting path is normalized, and trailing slashes are removed unless the path
 225 gets resolved to the root directory. Non-string `from` arguments are ignored.
 226
 227 Another way to think of it is as a sequence of `cd` commands in a shell.
 228
 229     path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
 230
 231 Is similar to:
 232
 233     cd foo/bar
 234     cd /tmp/file/
 235     cd ..
 236     cd a/../subfile
 237     pwd
 238
 239 The difference is that the different paths don't need to exist and may also be
 240 files.
 241
 242 Examples:
 243
 244     path.resolve('/foo/bar', './baz')
 245     // returns
 246     '/foo/bar/baz'
 247
 248     path.resolve('/foo/bar', '/tmp/file/')
 249     // returns
 250     '/tmp/file'
 251
 252     path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
 253     // if currently in /home/myself/node, it returns
 254     '/home/myself/node/wwwroot/static_files/gif/image.gif'
 255
 256 *Note:* If the arguments to `resolve` have zero-length strings then the current
 257         working directory will be used instead of them.
 258
 259 ## path.sep
 260
 261 The platform-specific file separator. `'\\'` or `'/'`.
 262
 263 An example on \*nix:
 264
 265     'foo/bar/baz'.split(path.sep)
 266     // returns
 267     ['foo', 'bar', 'baz']
 268
 269 An example on Windows:
 270
 271     'foo\\bar\\baz'.split(path.sep)
 272     // returns
 273     ['foo', 'bar', 'baz']
 274
 275 ## path.win32
 276
 277 Provide access to aforementioned `path` methods but always interact in a win32
 278 compatible way.
 279
 280 [`path.parse`]: #path_path_parse_pathstring