OLD | NEW |
| (Empty) |
1 A comprehensive, cross-platform path manipulation library for Dart. | |
2 | |
3 The pathos library provides common operations for manipulating file paths: | |
4 joining, splitting, normalizing, etc. | |
5 | |
6 We've tried very hard to make this library do the "right" thing on whatever | |
7 platform you run it on. When you use the top-level functions, it will assume the | |
8 current platform's path style and work with that. If you want to specifically | |
9 work with paths of a specific style, you can construct a `path.Builder` for that | |
10 style. | |
11 | |
12 ## Using | |
13 | |
14 The path library was designed to be imported with a prefix, though you don't | |
15 have to if you don't want to: | |
16 | |
17 import 'package:pathos/path.dart' as path; | |
18 | |
19 ## Top-level functions | |
20 | |
21 The most common way to use the library is through the top-level functions. | |
22 These manipulate path strings based on your current working directory and the | |
23 path style (POSIX, Windows, or URLs) of the host platform. | |
24 | |
25 ### String get current | |
26 | |
27 Gets the path to the current working directory. In the browser, this means the | |
28 current URL. When using dart2js, this currently returns `.` due to technical | |
29 constraints. In the future, it will return the current URL. | |
30 | |
31 ### String get separator | |
32 | |
33 Gets the path separator for the current platform. On Mac, Linux, and the | |
34 browser, this is `/`. On Windows, it's `\`. | |
35 | |
36 ### String absolute(String path) | |
37 | |
38 Converts [path] to an absolute path by resolving it relative to the current | |
39 working directory. If [path] is already an absolute path, just returns it. | |
40 | |
41 path.absolute('foo/bar.txt'); // -> /your/current/dir/foo/bar.txt | |
42 | |
43 ### String basename(String path) | |
44 | |
45 Gets the part of [path] after the last separator. | |
46 | |
47 path.basename('path/to/foo.dart'); // -> 'foo.dart' | |
48 path.basename('path/to'); // -> 'to' | |
49 | |
50 Trailing separators are ignored. | |
51 | |
52 builder.basename('path/to/'); // -> 'to' | |
53 | |
54 ### String basenameWithoutExtension(String path) | |
55 | |
56 Gets the part of [path] after the last separator, and without any trailing | |
57 file extension. | |
58 | |
59 path.basenameWithoutExtension('path/to/foo.dart'); // -> 'foo' | |
60 | |
61 Trailing separators are ignored. | |
62 | |
63 builder.basenameWithoutExtension('path/to/foo.dart/'); // -> 'foo' | |
64 | |
65 ### String dirname(String path) | |
66 | |
67 Gets the part of [path] before the last separator. | |
68 | |
69 path.dirname('path/to/foo.dart'); // -> 'path/to' | |
70 path.dirname('path/to'); // -> 'to' | |
71 | |
72 Trailing separators are ignored. | |
73 | |
74 builder.dirname('path/to/'); // -> 'path' | |
75 | |
76 ### String extension(String path) | |
77 | |
78 Gets the file extension of [path]: the portion of [basename] from the last | |
79 `.` to the end (including the `.` itself). | |
80 | |
81 path.extension('path/to/foo.dart'); // -> '.dart' | |
82 path.extension('path/to/foo'); // -> '' | |
83 path.extension('path.to/foo'); // -> '' | |
84 path.extension('path/to/foo.dart.js'); // -> '.js' | |
85 | |
86 If the file name starts with a `.`, then that is not considered the | |
87 extension: | |
88 | |
89 path.extension('~/.bashrc'); // -> '' | |
90 path.extension('~/.notes.txt'); // -> '.txt' | |
91 | |
92 ### String rootPrefix(String path) | |
93 | |
94 Returns the root of [path], if it's absolute, or the empty string if it's | |
95 relative. | |
96 | |
97 // Unix | |
98 path.rootPrefix('path/to/foo'); // -> '' | |
99 path.rootPrefix('/path/to/foo'); // -> '/' | |
100 | |
101 // Windows | |
102 path.rootPrefix(r'path\to\foo'); // -> '' | |
103 path.rootPrefix(r'C:\path\to\foo'); // -> r'C:\' | |
104 | |
105 // URL | |
106 path.rootPrefix('path/to/foo'); // -> '' | |
107 path.rootPrefix('http://dartlang.org/path/to/foo'); | |
108 // -> 'http://dartlang.org' | |
109 | |
110 ### bool isAbsolute(String path) | |
111 | |
112 Returns `true` if [path] is an absolute path and `false` if it is a relative | |
113 path. On POSIX systems, absolute paths start with a `/` (forward slash). On | |
114 Windows, an absolute path starts with `\\`, or a drive letter followed by `:/` | |
115 or `:\`. For URLs, absolute paths either start with a protocol and optional | |
116 hostname (e.g. `http://dartlang.org`, `file://`) or with a `/`. | |
117 | |
118 URLs that start with `/` are known as "root-relative", since they're relative to | |
119 the root of the current URL. Since root-relative paths are still absolute in | |
120 every other sense, [isAbsolute] will return true for them. They can be detected | |
121 using [isRootRelative]. | |
122 | |
123 ### bool isRelative(String path) | |
124 | |
125 Returns `true` if [path] is a relative path and `false` if it is absolute. | |
126 On POSIX systems, absolute paths start with a `/` (forward slash). On | |
127 Windows, an absolute path starts with `\\`, or a drive letter followed by | |
128 `:/` or `:\`. | |
129 | |
130 ### bool isRootRelative(String path) | |
131 | |
132 Returns `true` if [path] is a root-relative path and `false` if it's not. URLs | |
133 that start with `/` are known as "root-relative", since they're relative to the | |
134 root of the current URL. Since root-relative paths are still absolute in every | |
135 other sense, [isAbsolute] will return true for them. They can be detected using | |
136 [isRootRelative]. | |
137 | |
138 No POSIX and Windows paths are root-relative. | |
139 | |
140 ### String join(String part1, [String part2, String part3, ...]) | |
141 | |
142 Joins the given path parts into a single path using the current platform's | |
143 [separator]. Example: | |
144 | |
145 path.join('path', 'to', 'foo'); // -> 'path/to/foo' | |
146 | |
147 If any part ends in a path separator, then a redundant separator will not | |
148 be added: | |
149 | |
150 path.join('path/', 'to', 'foo'); // -> 'path/to/foo | |
151 | |
152 If a part is an absolute path, then anything before that will be ignored: | |
153 | |
154 path.join('path', '/to', 'foo'); // -> '/to/foo' | |
155 | |
156 ### List<String> split(String path) | |
157 | |
158 Splits [path] into its components using the current platform's [separator]. | |
159 | |
160 path.split('path/to/foo'); // -> ['path', 'to', 'foo'] | |
161 | |
162 The path will *not* be normalized before splitting. | |
163 | |
164 path.split('path/../foo'); // -> ['path', '..', 'foo'] | |
165 | |
166 If [path] is absolute, the root directory will be the first element in the | |
167 array. Example: | |
168 | |
169 // Unix | |
170 path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo'] | |
171 | |
172 // Windows | |
173 path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo'] | |
174 | |
175 // Browser | |
176 path.split('http://dartlang.org/path/to/foo'); | |
177 // -> ['http://dartlang.org', 'path', 'to', 'foo'] | |
178 | |
179 ### String normalize(String path) | |
180 | |
181 Normalizes [path], simplifying it by handling `..`, and `.`, and | |
182 removing redundant path separators whenever possible. | |
183 | |
184 path.normalize('path/./to/..//file.text'); // -> 'path/file.txt' | |
185 String normalize(String path) => _builder.normalize(path); | |
186 | |
187 ### String relative(String path, {String from}) | |
188 | |
189 Attempts to convert [path] to an equivalent relative path from the current | |
190 directory. | |
191 | |
192 // Given current directory is /root/path: | |
193 path.relative('/root/path/a/b.dart'); // -> 'a/b.dart' | |
194 path.relative('/root/other.dart'); // -> '../other.dart' | |
195 | |
196 If the [from] argument is passed, [path] is made relative to that instead. | |
197 | |
198 path.relative('/root/path/a/b.dart', | |
199 from: '/root/path'); // -> 'a/b.dart' | |
200 path.relative('/root/other.dart', | |
201 from: '/root/path'); // -> '../other.dart' | |
202 | |
203 Since there is no relative path from one drive letter to another on Windows, | |
204 this will return an absolute path in that case. | |
205 | |
206 // Windows | |
207 path.relative(r'D:\other', from: r'C:\home'); // -> 'D:\other' | |
208 | |
209 // URL | |
210 path.relative('http://dartlang.org', from: 'http://pub.dartlang.org'); | |
211 // -> 'http://dartlang.org' | |
212 | |
213 ### String withoutExtension(String path) | |
214 | |
215 Removes a trailing extension from the last part of [path]. | |
216 | |
217 withoutExtension('path/to/foo.dart'); // -> 'path/to/foo' | |
218 | |
219 ### String fromUri(Uri uri) | |
220 | |
221 Returns the path represented by [uri]. For POSIX and Windows styles, [uri] must | |
222 be a `file:` URI. For the URL style, this will just convert [uri] to a string. | |
223 | |
224 // POSIX | |
225 path.fromUri(Uri.parse('file:///path/to/foo')) | |
226 // -> '/path/to/foo' | |
227 | |
228 // Windows | |
229 path.fromUri(Uri.parse('file:///C:/path/to/foo')) | |
230 // -> r'C:\path\to\foo' | |
231 | |
232 // URL | |
233 path.fromUri(Uri.parse('http://dartlang.org/path/to/foo')) | |
234 // -> 'http://dartlang.org/path/to/foo' | |
235 | |
236 ### Uri toUri(String path) | |
237 | |
238 Returns the URI that represents [path]. For POSIX and Windows styles, this will | |
239 return a `file:` URI. For the URL style, this will just convert [path] to a | |
240 [Uri]. | |
241 | |
242 This will always convert relative paths to absolute ones before converting | |
243 to a URI. | |
244 | |
245 // POSIX | |
246 path.toUri('/path/to/foo') | |
247 // -> Uri.parse('file:///path/to/foo') | |
248 | |
249 // Windows | |
250 path.toUri(r'C:\path\to\foo') | |
251 // -> Uri.parse('file:///C:/path/to/foo') | |
252 | |
253 // URL | |
254 path.toUri('http://dartlang.org/path/to/foo') | |
255 // -> Uri.parse('http://dartlang.org/path/to/foo') | |
256 | |
257 ## The path.Builder class | |
258 | |
259 In addition to the functions, path exposes a `path.Builder` class. This lets | |
260 you configure the root directory and path style that paths are built using | |
261 explicitly instead of assuming the current working directory and host OS's path | |
262 style. | |
263 | |
264 You won't often use this, but it can be useful if you do a lot of path | |
265 manipulation relative to some root directory. | |
266 | |
267 var builder = new path.Builder(root: '/other/root'); | |
268 builder.relative('/other/root/foo.txt'); // -> 'foo.txt' | |
269 | |
270 It exposes the same methods and getters as the top-level functions, with the | |
271 addition of: | |
272 | |
273 ### new Builder({Style style, String root}) | |
274 | |
275 Creates a new path builder for the given style and root directory. | |
276 | |
277 If [style] is omitted, it uses the host operating system's path style. If | |
278 [root] is omitted, it defaults to the current working directory. If [root] | |
279 is relative, it is considered relative to the current working directory. | |
280 | |
281 ### Style style | |
282 | |
283 The style of path that this builder works with. | |
284 | |
285 ### String root | |
286 | |
287 The root directory that relative paths will be relative to. | |
288 | |
289 ### String get separator | |
290 | |
291 Gets the path separator for the builder's [style]. On Mac and Linux, | |
292 this is `/`. On Windows, it's `\`. | |
293 | |
294 ### String rootPrefix(String path) | |
295 | |
296 Returns the root of [path], if it's absolute, or an empty string if it's | |
297 relative. | |
298 | |
299 // Unix | |
300 builder.rootPrefix('path/to/foo'); // -> '' | |
301 builder.rootPrefix('/path/to/foo'); // -> '/' | |
302 | |
303 // Windows | |
304 builder.rootPrefix(r'path\to\foo'); // -> '' | |
305 builder.rootPrefix(r'C:\path\to\foo'); // -> r'C:\' | |
306 | |
307 // URL | |
308 builder.rootPrefix('path/to/foo'); // -> '' | |
309 builder.rootPrefix('http://dartlang.org/path/to/foo'); | |
310 // -> 'http://dartlang.org' | |
311 | |
312 ### String resolve(String part1, [String part2, String part3, ...]) | |
313 | |
314 Creates a new path by appending the given path parts to the [root]. | |
315 Equivalent to [join()] with [root] as the first argument. Example: | |
316 | |
317 var builder = new Builder(root: 'root'); | |
318 builder.resolve('path', 'to', 'foo'); // -> 'root/path/to/foo' | |
319 | |
320 ## The path.Style class | |
321 | |
322 The path library can work with three different "flavors" of path: POSIX, | |
323 Windows, and URLs. The differences between these are encapsulated by the | |
324 `path.Style` enum class. There are three instances of it: | |
325 | |
326 ### path.Style.posix | |
327 | |
328 POSIX-style paths use "/" (forward slash) as separators. Absolute paths | |
329 start with "/". Used by UNIX, Linux, Mac OS X, and others. | |
330 | |
331 ### path.Style.windows | |
332 | |
333 Windows paths use "\" (backslash) as separators. Absolute paths start with | |
334 a drive letter followed by a colon (example, "C:") or two backslashes | |
335 ("\\") for UNC paths. | |
336 | |
337 ### path.Style.url | |
338 | |
339 URLs aren't filesystem paths, but they're supported by Pathos to make it easier | |
340 to manipulate URL paths in the browser. | |
341 | |
342 URLs use "/" (forward slash) as separators. Absolute paths either start with a | |
343 protocol and optional hostname (e.g. `http://dartlang.org`, `file://`) or with | |
344 "/". | |
345 | |
346 ## FAQ | |
347 | |
348 ### Where can I use this? | |
349 | |
350 Pathos runs on the Dart VM and in the browser under both dart2js and Dartium. | |
351 Under dart2js, it currently returns "." as the current working directory, while | |
352 under Dartium it returns the current URL. | |
353 | |
354 ### Why doesn't this make paths first-class objects? | |
355 | |
356 When you have path *objects*, then every API that takes a path has to decide if | |
357 it accepts strings, path objects, or both. | |
358 | |
359 * Accepting strings is the most convenient, but then it seems weird to have | |
360 these path objects that aren't actually accepted by anything that needs a | |
361 path. Once you've created a path, you have to always call `.toString()` on | |
362 it before you can do anything useful with it. | |
363 | |
364 * Requiring objects forces users to wrap path strings in these objects, which | |
365 is tedious. It also means coupling that API to whatever library defines this | |
366 path class. If there are multiple "path" libraries that each define their | |
367 own path types, then any library that works with paths has to pick which one | |
368 it uses. | |
369 | |
370 * Taking both means you can't type your API. That defeats the purpose of | |
371 having a path type: why have a type if your APIs can't annotate that they | |
372 use it? | |
373 | |
374 Given that, we've decided this library should simply treat paths as strings. | |
375 | |
376 ### How cross-platform is this? | |
377 | |
378 We believe this library handles most of the corner cases of Windows paths | |
379 (POSIX paths are generally pretty straightforward): | |
380 | |
381 * It understands that *both* "/" and "\" are valid path separators, not just | |
382 "\". | |
383 | |
384 * It can accurately tell if a path is absolute based on drive-letters or UNC | |
385 prefix. | |
386 | |
387 * It understands that "/foo" is not an absolute path on Windows. | |
388 | |
389 * It knows that "C:\foo\one.txt" and "c:/foo\two.txt" are two files in the | |
390 same directory. | |
391 | |
392 If you find a problem, surprise or something that's unclear, please don't | |
393 hesitate to [file a bug](http://dartbug.com/new) and let us know. | |
OLD | NEW |