Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 256 lines (174 sloc) 6.121 kb
aef61ee @isaacs doc refactor: path
isaacs authored
1 # Path
e190c96 @miksago Splitting documentation
miksago authored
2
2d44dcc @isaacs doc: Add stability indicators to documentation
isaacs authored
3 Stability: 3 - Stable
4
4cf0ce5 @tshinnic docs: typos and minor edits in several modules
tshinnic authored
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:
e190c96 @miksago Splitting documentation
miksago authored
10
aef61ee @isaacs doc refactor: path
isaacs authored
11 ## path.normalize(p)
7c731ec @piscisaureus Path.resolve, path module windows compatibility
piscisaureus authored
12
13 Normalize a string path, taking care of `'..'` and `'.'` parts.
14
4cf0ce5 @tshinnic docs: typos and minor edits in several modules
tshinnic authored
15 When multiple slashes are found, they're replaced by a single one;
7c731ec @piscisaureus Path.resolve, path module windows compatibility
piscisaureus authored
16 when the path contains a trailing slash, it is preserved.
41e53e5 @serby path: add platform specific path delimiter
serby authored
17 On Windows backslashes are used.
7c731ec @piscisaureus Path.resolve, path module windows compatibility
piscisaureus authored
18
19 Example:
20
21 path.normalize('/foo/bar//baz/asdf/quux/..')
22 // returns
23 '/foo/bar/baz/asdf'
24
f2a78de @trevnorris doc: fix optional parameter parsing
trevnorris authored
25 ## path.join([path1][, path2][, ...])
e190c96 @miksago Splitting documentation
miksago authored
26
7c731ec @piscisaureus Path.resolve, path module windows compatibility
piscisaureus authored
27 Join all arguments together and normalize the resulting path.
9af0085 @bnoordhuis doc: path.join() arguments must be strings
bnoordhuis authored
28
29 Arguments must be strings. In v0.8, non-string arguments were
30 silently ignored. In v0.10 and up, an exception is thrown.
e190c96 @miksago Splitting documentation
miksago authored
31
32 Example:
33
20d7c47 @bnoordhuis Document that `path.join()` and `path.resolve()` ignore non-string ar…
bnoordhuis authored
34 path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
35 // returns
e190c96 @miksago Splitting documentation
miksago authored
36 '/foo/bar/baz/asdf'
37
20d7c47 @bnoordhuis Document that `path.join()` and `path.resolve()` ignore non-string ar…
bnoordhuis authored
38 path.join('foo', {}, 'bar')
36503b5 @kellygerber docs: update path.join() example for v0.10
kellygerber authored
39 // throws exception
40 TypeError: Arguments to path.join must be strings
20d7c47 @bnoordhuis Document that `path.join()` and `path.resolve()` ignore non-string ar…
bnoordhuis authored
41
aef61ee @isaacs doc refactor: path
isaacs authored
42 ## path.resolve([from ...], to)
e190c96 @miksago Splitting documentation
miksago authored
43
0114826 @piscisaureus Improve path.resolve documentation
piscisaureus authored
44 Resolves `to` to an absolute path.
e190c96 @miksago Splitting documentation
miksago authored
45
0114826 @piscisaureus Improve path.resolve documentation
piscisaureus authored
46 If `to` isn't already absolute `from` arguments are prepended in right to left
47 order, until an absolute path is found. If after using all `from` paths still
48 no absolute path is found, the current working directory is used as well. The
41e53e5 @serby path: add platform specific path delimiter
serby authored
49 resulting path is normalized, and trailing slashes are removed unless the path
9251889 @jgillich docs: fix non-string ignore note in path.resolve
jgillich authored
50 gets resolved to the root directory. Non-string `from` arguments are ignored.
e190c96 @miksago Splitting documentation
miksago authored
51
0114826 @piscisaureus Improve path.resolve documentation
piscisaureus authored
52 Another way to think of it is as a sequence of `cd` commands in a shell.
e190c96 @miksago Splitting documentation
miksago authored
53
0114826 @piscisaureus Improve path.resolve documentation
piscisaureus authored
54 path.resolve('foo/bar', '/tmp/file/', '..', 'a/../subfile')
e190c96 @miksago Splitting documentation
miksago authored
55
0114826 @piscisaureus Improve path.resolve documentation
piscisaureus authored
56 Is similar to:
57
58 cd foo/bar
59 cd /tmp/file/
60 cd ..
61 cd a/../subfile
62 pwd
63
64 The difference is that the different paths don't need to exist and may also be
65 files.
66
67 Examples:
e190c96 @miksago Splitting documentation
miksago authored
68
7c731ec @piscisaureus Path.resolve, path module windows compatibility
piscisaureus authored
69 path.resolve('/foo/bar', './baz')
70 // returns
0114826 @piscisaureus Improve path.resolve documentation
piscisaureus authored
71 '/foo/bar/baz'
e190c96 @miksago Splitting documentation
miksago authored
72
7c731ec @piscisaureus Path.resolve, path module windows compatibility
piscisaureus authored
73 path.resolve('/foo/bar', '/tmp/file/')
e190c96 @miksago Splitting documentation
miksago authored
74 // returns
7c731ec @piscisaureus Path.resolve, path module windows compatibility
piscisaureus authored
75 '/tmp/file'
76
77 path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
0114826 @piscisaureus Improve path.resolve documentation
piscisaureus authored
78 // if currently in /home/myself/node, it returns
79 '/home/myself/node/wwwroot/static_files/gif/image.gif'
e190c96 @miksago Splitting documentation
miksago authored
80
9026675 @hackedy path: add path.isAbsolute(path)
hackedy authored
81 ## path.isAbsolute(path)
82
83 Determines whether `path` is an absolute path. An absolute path will always
84 resolve to the same location, regardless of the working directory.
85
86 Posix examples:
87
88 path.isAbsolute('/foo/bar') // true
89 path.isAbsolute('/baz/..') // true
90 path.isAbsolute('qux/') // false
91 path.isAbsolute('.') // false
92
93 Windows examples:
94
95 path.isAbsolute('//server') // true
96 path.isAbsolute('C:/foo/..') // true
97 path.isAbsolute('bar\\baz') // false
98 path.isAbsolute('.') // false
99
aef61ee @isaacs doc refactor: path
isaacs authored
100 ## path.relative(from, to)
891a6f2 @cnwzhjs add the document of the new api routine: path.relative
cnwzhjs authored
101
102 Solve the relative path from `from` to `to`.
103
4cf0ce5 @tshinnic docs: typos and minor edits in several modules
tshinnic authored
104 At times we have two absolute paths, and we need to derive the relative
105 path from one to the other. This is actually the reverse transform of
106 `path.resolve`, which means we see that:
891a6f2 @cnwzhjs add the document of the new api routine: path.relative
cnwzhjs authored
107
108 path.resolve(from, path.relative(from, to)) == path.resolve(to)
109
110 Examples:
111
112 path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb')
113 // returns
114 '..\\..\\impl\\bbb'
115
116 path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
117 // returns
118 '../../impl/bbb'
119
aef61ee @isaacs doc refactor: path
isaacs authored
120 ## path.dirname(p)
e190c96 @miksago Splitting documentation
miksago authored
121
122 Return the directory name of a path. Similar to the Unix `dirname` command.
123
124 Example:
125
126 path.dirname('/foo/bar/baz/asdf/quux')
127 // returns
128 '/foo/bar/baz/asdf'
129
51b6b68 @trevnorris doc: fix brackets for optional parameters
trevnorris authored
130 ## path.basename(p[, ext])
e190c96 @miksago Splitting documentation
miksago authored
131
132 Return the last portion of a path. Similar to the Unix `basename` command.
133
134 Example:
135
136 path.basename('/foo/bar/baz/asdf/quux.html')
137 // returns
138 'quux.html'
139
140 path.basename('/foo/bar/baz/asdf/quux.html', '.html')
141 // returns
142 'quux'
143
aef61ee @isaacs doc refactor: path
isaacs authored
144 ## path.extname(p)
e190c96 @miksago Splitting documentation
miksago authored
145
4cf0ce5 @tshinnic docs: typos and minor edits in several modules
tshinnic authored
146 Return the extension of the path, from the last '.' to end of string
147 in the last portion of the path. If there is no '.' in the last portion
148 of the path or the first character of it is '.', then it returns
149 an empty string. Examples:
e190c96 @miksago Splitting documentation
miksago authored
150
151 path.extname('index.html')
11b2ee7 @silas Various doc tweaks (2-spaces vs tabs, EOL-whitespace, repl prompt, "w…
silas authored
152 // returns
e190c96 @miksago Splitting documentation
miksago authored
153 '.html'
154
154d9d2 @mquandalle doc: add an example about multiple extensions
mquandalle authored
155 path.extname('index.coffee.md')
156 // returns
157 '.md'
158
4cf0ce5 @tshinnic docs: typos and minor edits in several modules
tshinnic authored
159 path.extname('index.')
160 // returns
161 '.'
162
e190c96 @miksago Splitting documentation
miksago authored
163 path.extname('index')
164 // returns
165 ''
4bd54da @npcode path: add path.sep to get the path separator.
npcode authored
166
167 ## path.sep
168
169 The platform-specific file separator. `'\\'` or `'/'`.
170
41e53e5 @serby path: add platform specific path delimiter
serby authored
171 An example on *nix:
4bd54da @npcode path: add path.sep to get the path separator.
npcode authored
172
173 'foo/bar/baz'.split(path.sep)
174 // returns
175 ['foo', 'bar', 'baz']
176
41e53e5 @serby path: add platform specific path delimiter
serby authored
177 An example on Windows:
4bd54da @npcode path: add path.sep to get the path separator.
npcode authored
178
179 'foo\\bar\\baz'.split(path.sep)
180 // returns
181 ['foo', 'bar', 'baz']
41e53e5 @serby path: add platform specific path delimiter
serby authored
182
183 ## path.delimiter
184
185 The platform-specific path delimiter, `;` or `':'`.
186
187 An example on *nix:
188
189 console.log(process.env.PATH)
190 // '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'
191
192 process.env.PATH.split(path.delimiter)
193 // returns
194 ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']
195
196 An example on Windows:
197
198 console.log(process.env.PATH)
199 // 'C:\Windows\system32;C:\Windows;C:\Program Files\nodejs\'
200
201 process.env.PATH.split(path.delimiter)
202 // returns
2b64132 @stcruy doc: fix '\\' typos on Windows
stcruy authored
203 ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\nodejs\\']
6a90a06 @tjfontaine path: allow calling platform specific methods
tjfontaine authored
204
2d17193 @roryrjb path: added parse() and format() functions
roryrjb authored
205 ## path.parse(pathString)
206
207 Returns an object from a path string.
208
209 An example on *nix:
210
211 path.parse('/home/user/dir/file.txt')
212 // returns
213 {
214 root : "/",
215 dir : "/home/user/dir",
216 base : "file.txt",
217 ext : ".txt",
218 name : "file"
219 }
220
221 An example on Windows:
222
223 path.parse('C:\\path\\dir\\index.html')
224 // returns
225 {
2b64132 @stcruy doc: fix '\\' typos on Windows
stcruy authored
226 root : "C:\\",
227 dir : "C:\\path\\dir",
2d17193 @roryrjb path: added parse() and format() functions
roryrjb authored
228 base : "index.html",
229 ext : ".html",
230 name : "index"
231 }
232
233 ## path.format(pathObject)
234
235 Returns a path string from an object, the opposite of `path.parse` above.
236
237 path.format({
238 root : "/",
239 dir : "/home/user/dir",
240 base : "file.txt",
241 ext : ".txt",
242 name : "file"
243 })
244 // returns
245 '/home/user/dir/file.txt'
246
6a90a06 @tjfontaine path: allow calling platform specific methods
tjfontaine authored
247 ## path.posix
248
249 Provide access to aforementioned `path` methods but always interact in a posix
250 compatible way.
251
252 ## path.win32
253
254 Provide access to aforementioned `path` methods but always interact in a win32
255 compatible way.
Something went wrong with that request. Please try again.