OLD | NEW |
---|---|
(Empty) | |
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 library path.context; | |
6 | |
7 import 'style.dart'; | |
8 import 'parsed_path.dart'; | |
9 import 'path_exception.dart'; | |
10 import '../path.dart' as p; | |
11 | |
12 /// An instantiable class for manipulating paths. Unlike the top-level | |
13 /// functions, this lets you explicitly select what platform the paths will use. | |
14 class Context { | |
15 /// Creates a new path context for the given style and current directory. | |
16 /// | |
17 /// If [style] is omitted, it uses the host operating system's path style. If | |
18 /// only [current] is omitted, it defaults ".". If *both* [style] and | |
19 /// [current] are omitted, [current] defaults to the real current working | |
20 /// directory. | |
21 /// | |
22 /// On the browser, [style] defaults to [Style.url] and [current] defaults to | |
23 /// the current URL. | |
24 factory Context({Style style, String current}) { | |
25 if (current == null) { | |
26 if (style == null) { | |
27 current = p.current; | |
28 } else { | |
29 current = "."; | |
30 } | |
31 } | |
32 | |
33 if (style == null) style = Style.platform; | |
34 | |
35 return new Context._(style, current); | |
36 } | |
37 | |
38 Context._(this.style, this.current); | |
39 | |
40 /// The style of path that this context works with. | |
41 final Style style; | |
42 | |
43 /// The current directory that relative paths will be relative to. | |
44 final String current; | |
45 | |
46 /// Gets the path separator for the context's [style]. On Mac and Linux, | |
47 /// this is `/`. On Windows, it's `\`. | |
48 String get separator => style.separator; | |
49 | |
50 /// Creates a new path by appending the given path parts to [current]. | |
51 /// Equivalent to [join()] with [current] as the first argument. Example: | |
52 /// | |
53 /// var context = new Context(current: '/root'); | |
54 /// context.absolute('path', 'to', 'foo'); // -> '/root/path/to/foo' | |
55 /// | |
56 /// If [current] isn't absolute, this won't return an absolute path. | |
57 String absolute(String part1, [String part2, String part3, String part4, | |
58 String part5, String part6, String part7]) { | |
59 return join(current, part1, part2, part3, part4, part5, part6, part7); | |
60 } | |
61 | |
62 /// Gets the part of [path] after the last separator on the context's | |
63 /// platform. | |
64 /// | |
65 /// context.basename('path/to/foo.dart'); // -> 'foo.dart' | |
66 /// context.basename('path/to'); // -> 'to' | |
67 /// | |
68 /// Trailing separators are ignored. | |
69 /// | |
70 /// context.basename('path/to/'); // -> 'to' | |
71 String basename(String path) => _parse(path).basename; | |
72 | |
73 /// Gets the part of [path] after the last separator on the context's | |
74 /// platform, and without any trailing file extension. | |
75 /// | |
76 /// context.basenameWithoutExtension('path/to/foo.dart'); // -> 'foo' | |
77 /// | |
78 /// Trailing separators are ignored. | |
79 /// | |
80 /// context.basenameWithoutExtension('path/to/foo.dart/'); // -> 'foo' | |
81 String basenameWithoutExtension(String path) => | |
82 _parse(path).basenameWithoutExtension; | |
83 | |
84 /// Gets the part of [path] before the last separator. | |
85 /// | |
86 /// context.dirname('path/to/foo.dart'); // -> 'path/to' | |
87 /// context.dirname('path/to'); // -> 'path' | |
88 /// | |
89 /// Trailing separators are ignored. | |
90 /// | |
91 /// context.dirname('path/to/'); // -> 'path' | |
92 String dirname(String path) { | |
93 var parsed = _parse(path); | |
94 parsed.removeTrailingSeparators(); | |
95 if (parsed.parts.isEmpty) return parsed.root == null ? '.' : parsed.root; | |
96 if (parsed.parts.length == 1) { | |
97 return parsed.root == null ? '.' : parsed.root; | |
98 } | |
99 parsed.parts.removeLast(); | |
100 parsed.separators.removeLast(); | |
101 parsed.removeTrailingSeparators(); | |
102 return parsed.toString(); | |
103 } | |
104 | |
105 /// Gets the file extension of [path]: the portion of [basename] from the last | |
106 /// `.` to the end (including the `.` itself). | |
107 /// | |
108 /// context.extension('path/to/foo.dart'); // -> '.dart' | |
109 /// context.extension('path/to/foo'); // -> '' | |
110 /// context.extension('path.to/foo'); // -> '' | |
111 /// context.extension('path/to/foo.dart.js'); // -> '.js' | |
112 /// | |
113 /// If the file name starts with a `.`, then it is not considered an | |
114 /// extension: | |
115 /// | |
116 /// context.extension('~/.bashrc'); // -> '' | |
117 /// context.extension('~/.notes.txt'); // -> '.txt' | |
118 String extension(String path) => _parse(path).extension; | |
119 | |
120 // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed. | |
121 /// Returns the root of [path], if it's absolute, or an empty string if it's | |
Bob Nystrom
2013/11/18 20:43:21
Remove comma before first "if".
nweiz
2013/11/19 20:44:53
Done.
| |
122 /// relative. | |
123 /// | |
124 /// // Unix | |
125 /// context.rootPrefix('path/to/foo'); // -> '' | |
126 /// context.rootPrefix('/path/to/foo'); // -> '/' | |
127 /// | |
128 /// // Windows | |
129 /// context.rootPrefix(r'path\to\foo'); // -> '' | |
130 /// context.rootPrefix(r'C:\path\to\foo'); // -> r'C:\' | |
131 /// | |
132 /// // URL | |
133 /// context.rootPrefix('path/to/foo'); // -> '' | |
134 /// context.rootPrefix('http://dartlang.org/path/to/foo'); | |
135 /// // -> 'http://dartlang.org' | |
136 String rootPrefix(String path) { | |
137 var root = _parse(path).root; | |
138 return root == null ? '' : root; | |
139 } | |
140 | |
141 /// Returns `true` if [path] is an absolute path and `false` if it is a | |
142 /// relative path. | |
143 /// | |
144 /// On POSIX systems, absolute paths start with a `/` (forward slash). On | |
145 /// Windows, an absolute path starts with `\\`, or a drive letter followed by | |
146 /// `:/` or `:\`. For URLs, absolute paths either start with a protocol and | |
147 /// optional hostname (e.g. `http://dartlang.org`, `file://`) or with a `/`. | |
148 /// | |
149 /// URLs that start with `/` are known as "root-relative", since they're | |
150 /// relative to the root of the current URL. Since root-relative paths are | |
151 /// still absolute in every other sense, [isAbsolute] will return true for | |
152 /// them. They can be detected using [isRootRelative]. | |
153 bool isAbsolute(String path) => _parse(path).isAbsolute; | |
154 | |
155 /// Returns `true` if [path] is a relative path and `false` if it is absolute. | |
156 /// On POSIX systems, absolute paths start with a `/` (forward slash). On | |
157 /// Windows, an absolute path starts with `\\`, or a drive letter followed by | |
158 /// `:/` or `:\`. | |
159 bool isRelative(String path) => !this.isAbsolute(path); | |
160 | |
161 /// Returns `true` if [path] is a root-relative path and `false` if it's not. | |
162 /// | |
163 /// URLs that start with `/` are known as "root-relative", since they're | |
164 /// relative to the root of the current URL. Since root-relative paths are | |
165 /// still absolute in every other sense, [isAbsolute] will return true for | |
166 /// them. They can be detected using [isRootRelative]. | |
167 /// | |
168 /// No POSIX and Windows paths are root-relative. | |
169 bool isRootRelative(String path) => _parse(path).isRootRelative; | |
170 | |
171 /// Joins the given path parts into a single path. Example: | |
172 /// | |
173 /// context.join('path', 'to', 'foo'); // -> 'path/to/foo' | |
174 /// | |
175 /// If any part ends in a path separator, then a redundant separator will not | |
176 /// be added: | |
177 /// | |
178 /// context.join('path/', 'to', 'foo'); // -> 'path/to/foo | |
179 /// | |
180 /// If a part is an absolute path, then anything before that will be ignored: | |
181 /// | |
182 /// context.join('path', '/to', 'foo'); // -> '/to/foo' | |
183 /// | |
184 String join(String part1, [String part2, String part3, String part4, | |
185 String part5, String part6, String part7, String part8]) { | |
186 var parts = [part1, part2, part3, part4, part5, part6, part7, part8]; | |
187 _validateArgList("join", parts); | |
188 return joinAll(parts.where((part) => part != null)); | |
189 } | |
190 | |
191 /// Joins the given path parts into a single path. Example: | |
192 /// | |
193 /// context.joinAll(['path', 'to', 'foo']); // -> 'path/to/foo' | |
194 /// | |
195 /// If any part ends in a path separator, then a redundant separator will not | |
196 /// be added: | |
197 /// | |
198 /// context.joinAll(['path/', 'to', 'foo']); // -> 'path/to/foo | |
199 /// | |
200 /// If a part is an absolute path, then anything before that will be ignored: | |
201 /// | |
202 /// context.joinAll(['path', '/to', 'foo']); // -> '/to/foo' | |
203 /// | |
204 /// For a fixed number of parts, [join] is usually terser. | |
205 String joinAll(Iterable<String> parts) { | |
206 var buffer = new StringBuffer(); | |
207 var needsSeparator = false; | |
208 var isAbsoluteAndNotRootRelative = false; | |
209 | |
210 for (var part in parts.where((part) => part != '')) { | |
211 if (this.isRootRelative(part) && isAbsoluteAndNotRootRelative) { | |
212 // If the new part is root-relative, it preserves the previous root but | |
213 // replaces the path after it. | |
214 var parsed = _parse(part); | |
215 parsed.root = this.rootPrefix(buffer.toString()); | |
216 if (parsed.root.contains(style.needsSeparatorPattern)) { | |
217 parsed.separators[0] = style.separator; | |
218 } | |
219 buffer.clear(); | |
220 buffer.write(parsed.toString()); | |
221 } else if (this.isAbsolute(part)) { | |
222 isAbsoluteAndNotRootRelative = !this.isRootRelative(part); | |
223 // An absolute path discards everything before it. | |
224 buffer.clear(); | |
225 buffer.write(part); | |
226 } else { | |
227 if (part.length > 0 && part[0].contains(style.separatorPattern)) { | |
228 // The part starts with a separator, so we don't need to add one. | |
229 } else if (needsSeparator) { | |
230 buffer.write(separator); | |
231 } | |
232 | |
233 buffer.write(part); | |
234 } | |
235 | |
236 // Unless this part ends with a separator, we'll need to add one before | |
237 // the next part. | |
238 needsSeparator = part.contains(style.needsSeparatorPattern); | |
239 } | |
240 | |
241 return buffer.toString(); | |
242 } | |
243 | |
244 // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed. | |
245 /// Splits [path] into its components using the current platform's | |
246 /// [separator]. Example: | |
247 /// | |
248 /// context.split('path/to/foo'); // -> ['path', 'to', 'foo'] | |
249 /// | |
250 /// The path will *not* be normalized before splitting. | |
251 /// | |
252 /// context.split('path/../foo'); // -> ['path', '..', 'foo'] | |
253 /// | |
254 /// If [path] is absolute, the root directory will be the first element in the | |
255 /// array. Example: | |
256 /// | |
257 /// // Unix | |
258 /// context.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo'] | |
259 /// | |
260 /// // Windows | |
261 /// context.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo'] | |
262 List<String> split(String path) { | |
263 var parsed = _parse(path); | |
264 // Filter out empty parts that exist due to multiple separators in a row. | |
265 parsed.parts = parsed.parts.where((part) => !part.isEmpty) | |
266 .toList(); | |
267 if (parsed.root != null) parsed.parts.insert(0, parsed.root); | |
268 return parsed.parts; | |
269 } | |
270 | |
271 /// Normalizes [path], simplifying it by handling `..`, and `.`, and | |
272 /// removing redundant path separators whenever possible. | |
273 /// | |
274 /// context.normalize('path/./to/..//file.text'); // -> 'path/file.txt' | |
275 String normalize(String path) { | |
276 var parsed = _parse(path); | |
277 parsed.normalize(); | |
278 return parsed.toString(); | |
279 } | |
280 | |
281 /// Attempts to convert [path] to an equivalent relative path relative to | |
282 /// [root]. | |
283 /// | |
284 /// var context = new Context(current: '/root/path'); | |
285 /// context.relative('/root/path/a/b.dart'); // -> 'a/b.dart' | |
286 /// context.relative('/root/other.dart'); // -> '../other.dart' | |
287 /// | |
288 /// If the [from] argument is passed, [path] is made relative to that instead. | |
289 /// | |
290 /// context.relative('/root/path/a/b.dart', | |
291 /// from: '/root/path'); // -> 'a/b.dart' | |
292 /// context.relative('/root/other.dart', | |
293 /// from: '/root/path'); // -> '../other.dart' | |
294 /// | |
295 /// If [path] and/or [from] are relative paths, they are assumed to be | |
296 /// relative to [current]. | |
297 /// | |
298 /// Since there is no relative path from one drive letter to another on | |
299 /// Windows, this will return an absolute path in that case. | |
300 /// | |
301 /// context.relative(r'D:\other', from: r'C:\other'); // -> 'D:\other' | |
302 /// | |
303 /// This will also return an absolute path if an absolute [path] is passed to | |
304 /// a context with a relative path for [current]. | |
305 /// | |
306 /// var context = new Context(r'some/relative/path'); | |
307 /// context.relative(r'/absolute/path'); // -> '/absolute/path' | |
308 /// | |
309 /// If [root] is relative, it may be impossible to determine a path from | |
310 /// [from] to [path]. For example, if [root] and [path] are "." and [from] is | |
311 /// "/", no path can be determined. In this case, a [PathException] will be | |
312 /// thrown. | |
313 String relative(String path, {String from}) { | |
314 from = from == null ? current : this.join(current, from); | |
315 | |
316 // We can't determine the path from a relative path to an absolute path. | |
317 if (this.isRelative(from) && this.isAbsolute(path)) { | |
318 return this.normalize(path); | |
319 } | |
320 | |
321 // If the given path is relative, resolve it relative to the context's | |
322 // current directory. | |
323 if (this.isRelative(path) || this.isRootRelative(path)) { | |
324 path = this.absolute(path); | |
325 } | |
326 | |
327 // If the path is still relative and `from` is absolute, we're unable to | |
328 // find a path from `from` to `path`. | |
329 if (this.isRelative(path) && this.isAbsolute(from)) { | |
330 throw new PathException('Unable to find a path to "$path" from "$from".'); | |
331 } | |
332 | |
333 var fromParsed = _parse(from)..normalize(); | |
334 var pathParsed = _parse(path)..normalize(); | |
335 | |
336 if (fromParsed.parts.length > 0 && fromParsed.parts[0] == '.') { | |
337 return pathParsed.toString(); | |
338 } | |
339 | |
340 // If the root prefixes don't match (for example, different drive letters | |
341 // on Windows), then there is no relative path, so just return the absolute | |
342 // one. In Windows, drive letters are case-insenstive and we allow | |
343 // calculation of relative paths, even if a path has not been normalized. | |
344 if (fromParsed.root != pathParsed.root && | |
345 ((fromParsed.root == null || pathParsed.root == null) || | |
346 fromParsed.root.toLowerCase().replaceAll('/', '\\') != | |
347 pathParsed.root.toLowerCase().replaceAll('/', '\\'))) { | |
348 return pathParsed.toString(); | |
349 } | |
350 | |
351 // Strip off their common prefix. | |
352 while (fromParsed.parts.length > 0 && pathParsed.parts.length > 0 && | |
353 fromParsed.parts[0] == pathParsed.parts[0]) { | |
354 fromParsed.parts.removeAt(0); | |
355 fromParsed.separators.removeAt(1); | |
356 pathParsed.parts.removeAt(0); | |
357 pathParsed.separators.removeAt(1); | |
358 } | |
359 | |
360 // If there are any directories left in the from path, we need to walk up | |
361 // out of them. If a directory left in the from path is '..', it cannot | |
362 // be cancelled by adding a '..'. | |
363 if (fromParsed.parts.length > 0 && fromParsed.parts[0] == '..') { | |
364 throw new PathException('Unable to find a path to "$path" from "$from".'); | |
365 } | |
366 pathParsed.parts.insertAll(0, | |
367 new List.filled(fromParsed.parts.length, '..')); | |
368 pathParsed.separators[0] = ''; | |
369 pathParsed.separators.insertAll(1, | |
370 new List.filled(fromParsed.parts.length, style.separator)); | |
371 | |
372 // Corner case: the paths completely collapsed. | |
373 if (pathParsed.parts.length == 0) return '.'; | |
374 | |
375 // Corner case: path was '.' and some '..' directories were added in front. | |
376 // Don't add a final '/.' in that case. | |
377 if (pathParsed.parts.length > 1 && pathParsed.parts.last == '.') { | |
378 pathParsed.parts.removeLast(); | |
379 pathParsed.separators..removeLast()..removeLast()..add(''); | |
380 } | |
381 | |
382 // Make it relative. | |
383 pathParsed.root = ''; | |
384 pathParsed.removeTrailingSeparators(); | |
385 | |
386 return pathParsed.toString(); | |
387 } | |
388 | |
389 /// Returns `true` if [child] is a path beneath `parent`, and `false` | |
390 /// otherwise. | |
391 /// | |
392 /// path.isWithin('/root/path', '/root/path/a'); // -> true | |
393 /// path.isWithin('/root/path', '/root/other'); // -> false | |
394 /// path.isWithin('/root/path', '/root/path'); // -> false | |
395 bool isWithin(String parent, String child) { | |
396 var relative; | |
397 try { | |
398 relative = this.relative(child, from: parent); | |
399 } on PathException catch (_) { | |
400 // If no relative path from [parent] to [child] is found, [child] | |
401 // definitely isn't a child of [parent]. | |
402 return false; | |
403 } | |
404 | |
405 var parts = this.split(relative); | |
406 return this.isRelative(relative) && parts.first != '..' && | |
407 parts.first != '.'; | |
408 } | |
409 | |
410 /// Removes a trailing extension from the last part of [path]. | |
411 /// | |
412 /// context.withoutExtension('path/to/foo.dart'); // -> 'path/to/foo' | |
413 String withoutExtension(String path) { | |
414 var parsed = _parse(path); | |
415 | |
416 for (var i = parsed.parts.length - 1; i >= 0; i--) { | |
417 if (!parsed.parts[i].isEmpty) { | |
418 parsed.parts[i] = parsed.basenameWithoutExtension; | |
419 break; | |
420 } | |
421 } | |
422 | |
423 return parsed.toString(); | |
424 } | |
425 | |
426 /// Returns the path represented by [uri]. | |
427 /// | |
428 /// For POSIX and Windows styles, [uri] must be a `file:` URI. For the URL | |
429 /// style, this will just convert [uri] to a string. | |
430 /// | |
431 /// // POSIX | |
432 /// context.fromUri(Uri.parse('file:///path/to/foo')) | |
433 /// // -> '/path/to/foo' | |
434 /// | |
435 /// // Windows | |
436 /// context.fromUri(Uri.parse('file:///C:/path/to/foo')) | |
437 /// // -> r'C:\path\to\foo' | |
438 /// | |
439 /// // URL | |
440 /// context.fromUri(Uri.parse('http://dartlang.org/path/to/foo')) | |
441 /// // -> 'http://dartlang.org/path/to/foo' | |
442 String fromUri(Uri uri) => style.pathFromUri(uri); | |
443 | |
444 /// Returns the URI that represents [path]. | |
445 /// | |
446 /// For POSIX and Windows styles, this will return a `file:` URI. For the URL | |
447 /// style, this will just convert [path] to a [Uri]. | |
448 /// | |
449 /// // POSIX | |
450 /// context.toUri('/path/to/foo') | |
451 /// // -> Uri.parse('file:///path/to/foo') | |
452 /// | |
453 /// // Windows | |
454 /// context.toUri(r'C:\path\to\foo') | |
455 /// // -> Uri.parse('file:///C:/path/to/foo') | |
456 /// | |
457 /// // URL | |
458 /// context.toUri('http://dartlang.org/path/to/foo') | |
459 /// // -> Uri.parse('http://dartlang.org/path/to/foo') | |
460 Uri toUri(String path) { | |
461 if (isRelative(path)) { | |
462 return style.relativePathToUri(path); | |
463 } else { | |
464 return style.absolutePathToUri(join(current, path)); | |
465 } | |
466 } | |
467 | |
468 ParsedPath _parse(String path) => new ParsedPath.parse(path, style); | |
469 } | |
470 | |
471 /// Validates that there are no non-null arguments following a null one and | |
472 /// throws an appropriate [ArgumentError] on failure. | |
473 _validateArgList(String method, List<String> args) { | |
474 for (var i = 1; i < args.length; i++) { | |
475 // Ignore nulls hanging off the end. | |
476 if (args[i] == null || args[i - 1] != null) continue; | |
477 | |
478 var numArgs; | |
479 for (numArgs = args.length; numArgs >= 1; numArgs--) { | |
480 if (args[numArgs - 1] != null) break; | |
481 } | |
482 | |
483 // Show the arguments. | |
484 var message = new StringBuffer(); | |
485 message.write("$method("); | |
486 message.write(args.take(numArgs) | |
487 .map((arg) => arg == null ? "null" : '"$arg"') | |
488 .join(", ")); | |
489 message.write("): part ${i - 1} was null, but part $i was not."); | |
490 throw new ArgumentError(message.toString()); | |
491 } | |
492 } | |
OLD | NEW |