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