OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 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. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /// A comprehensive, cross-platform path manipulation library. | 5 /// A comprehensive, cross-platform path manipulation library. |
6 /// | 6 /// |
7 /// ## Installing ## | 7 /// ## Installing ## |
8 /// | 8 /// |
9 /// Use [pub][] to install this package. Add the following to your | 9 /// Use [pub][] to install this package. Add the following to your |
10 /// `pubspec.yaml` file. | 10 /// `pubspec.yaml` file. |
(...skipping 26 matching lines...) Expand all Loading... |
37 /// | 37 /// |
38 /// If you want to work with paths for a specific platform regardless of the | 38 /// If you want to work with paths for a specific platform regardless of the |
39 /// underlying platform that the program is running on, you can create a | 39 /// underlying platform that the program is running on, you can create a |
40 /// [Context] and give it an explicit [Style]: | 40 /// [Context] and give it an explicit [Style]: |
41 /// | 41 /// |
42 /// var context = new path.Context(style: Style.windows); | 42 /// var context = new path.Context(style: Style.windows); |
43 /// context.join("directory", "file.txt"); | 43 /// context.join("directory", "file.txt"); |
44 /// | 44 /// |
45 /// This will join "directory" and "file.txt" using the Windows path separator, | 45 /// This will join "directory" and "file.txt" using the Windows path separator, |
46 /// even when the program is run on a POSIX machine. | 46 /// even when the program is run on a POSIX machine. |
47 library path; | |
48 | |
49 import 'src/context.dart'; | 47 import 'src/context.dart'; |
50 import 'src/style.dart'; | 48 import 'src/style.dart'; |
51 | 49 |
52 export 'src/context.dart' hide createInternal; | 50 export 'src/context.dart' hide createInternal; |
53 export 'src/path_exception.dart'; | 51 export 'src/path_exception.dart'; |
54 export 'src/style.dart'; | 52 export 'src/style.dart'; |
55 | 53 |
56 /// A default context for manipulating POSIX paths. | 54 /// A default context for manipulating POSIX paths. |
57 final Context posix = new Context(style: Style.posix); | 55 final Context posix = new Context(style: Style.posix); |
58 | 56 |
59 /// A default context for manipulating Windows paths. | 57 /// A default context for manipulating Windows paths. |
60 final Context windows = new Context(style: Style.windows); | 58 final Context windows = new Context(style: Style.windows); |
61 | 59 |
62 /// A default context for manipulating URLs. | 60 /// A default context for manipulating URLs. |
| 61 /// |
| 62 /// URL path equality is undefined for paths that differ only in their |
| 63 /// percent-encoding or only in the case of their host segment. |
63 final Context url = new Context(style: Style.url); | 64 final Context url = new Context(style: Style.url); |
64 | 65 |
65 /// The system path context. | 66 /// The system path context. |
66 /// | 67 /// |
67 /// This differs from a context created with [new Context] in that its | 68 /// This differs from a context created with [new Context] in that its |
68 /// [Context.current] is always the current working directory, rather than being | 69 /// [Context.current] is always the current working directory, rather than being |
69 /// set once when the context is created. | 70 /// set once when the context is created. |
70 final Context context = createInternal(); | 71 final Context context = createInternal(); |
71 | 72 |
72 /// Returns the [Style] of the current context. | 73 /// Returns the [Style] of the current context. |
(...skipping 203 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
276 /// path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo'] | 277 /// path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo'] |
277 /// | 278 /// |
278 /// // Windows | 279 /// // Windows |
279 /// path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo'] | 280 /// path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo'] |
280 /// | 281 /// |
281 /// // Browser | 282 /// // Browser |
282 /// path.split('http://dartlang.org/path/to/foo'); | 283 /// path.split('http://dartlang.org/path/to/foo'); |
283 /// // -> ['http://dartlang.org', 'path', 'to', 'foo'] | 284 /// // -> ['http://dartlang.org', 'path', 'to', 'foo'] |
284 List<String> split(String path) => context.split(path); | 285 List<String> split(String path) => context.split(path); |
285 | 286 |
| 287 /// Canonicalizes [path]. |
| 288 /// |
| 289 /// This is guaranteed to return the same path for two different input paths |
| 290 /// if and only if both input paths point to the same location. Unlike |
| 291 /// [normalize], it returns absolute paths when possible and canonicalizes |
| 292 /// ASCII case on Windows. |
| 293 /// |
| 294 /// Note that this does not resolve symlinks. |
| 295 /// |
| 296 /// If you want a map that uses path keys, it's probably more efficient to |
| 297 /// pass [equals] and [hash] to [new HashMap] than it is to canonicalize every |
| 298 /// key. |
| 299 String canonicalize(String path) => context.canonicalize(path); |
| 300 |
286 /// Normalizes [path], simplifying it by handling `..`, and `.`, and | 301 /// Normalizes [path], simplifying it by handling `..`, and `.`, and |
287 /// removing redundant path separators whenever possible. | 302 /// removing redundant path separators whenever possible. |
288 /// | 303 /// |
| 304 /// Note that this is *not* guaranteed to return the same result for two |
| 305 /// equivalent input paths. For that, see [canonicalize]. Or, if you're using |
| 306 /// paths as map keys, pass [equals] and [hash] to [new HashMap]. |
| 307 /// |
289 /// path.normalize('path/./to/..//file.text'); // -> 'path/file.txt' | 308 /// path.normalize('path/./to/..//file.text'); // -> 'path/file.txt' |
290 String normalize(String path) => context.normalize(path); | 309 String normalize(String path) => context.normalize(path); |
291 | 310 |
292 /// Attempts to convert [path] to an equivalent relative path from the current | 311 /// Attempts to convert [path] to an equivalent relative path from the current |
293 /// directory. | 312 /// directory. |
294 /// | 313 /// |
295 /// // Given current directory is /root/path: | 314 /// // Given current directory is /root/path: |
296 /// path.relative('/root/path/a/b.dart'); // -> 'a/b.dart' | 315 /// path.relative('/root/path/a/b.dart'); // -> 'a/b.dart' |
297 /// path.relative('/root/other.dart'); // -> '../other.dart' | 316 /// path.relative('/root/other.dart'); // -> '../other.dart' |
298 /// | 317 /// |
(...skipping 20 matching lines...) Expand all Loading... |
319 String relative(String path, {String from}) => | 338 String relative(String path, {String from}) => |
320 context.relative(path, from: from); | 339 context.relative(path, from: from); |
321 | 340 |
322 /// Returns `true` if [child] is a path beneath `parent`, and `false` otherwise. | 341 /// Returns `true` if [child] is a path beneath `parent`, and `false` otherwise. |
323 /// | 342 /// |
324 /// path.isWithin('/root/path', '/root/path/a'); // -> true | 343 /// path.isWithin('/root/path', '/root/path/a'); // -> true |
325 /// path.isWithin('/root/path', '/root/other'); // -> false | 344 /// path.isWithin('/root/path', '/root/other'); // -> false |
326 /// path.isWithin('/root/path', '/root/path') // -> false | 345 /// path.isWithin('/root/path', '/root/path') // -> false |
327 bool isWithin(String parent, String child) => context.isWithin(parent, child); | 346 bool isWithin(String parent, String child) => context.isWithin(parent, child); |
328 | 347 |
| 348 /// Returns `true` if [path1] points to the same location as [path2], and |
| 349 /// `false` otherwise. |
| 350 /// |
| 351 /// The [hash] function returns a hash code that matches these equality |
| 352 /// semantics. |
| 353 bool equals(String path1, String path2) => context.equals(path1, path2); |
| 354 |
| 355 /// Returns a hash code for [path] such that, if [equals] returns `true` for two |
| 356 /// paths, their hash codes are the same. |
| 357 /// |
| 358 /// Note that the same path may have different hash codes on different platforms |
| 359 /// or with different [current] directories. |
| 360 int hash(String path) => context.hash(path); |
| 361 |
329 /// Removes a trailing extension from the last part of [path]. | 362 /// Removes a trailing extension from the last part of [path]. |
330 /// | 363 /// |
331 /// withoutExtension('path/to/foo.dart'); // -> 'path/to/foo' | 364 /// withoutExtension('path/to/foo.dart'); // -> 'path/to/foo' |
332 String withoutExtension(String path) => context.withoutExtension(path); | 365 String withoutExtension(String path) => context.withoutExtension(path); |
333 | 366 |
334 /// Returns the path represented by [uri], which may be a [String] or a [Uri]. | 367 /// Returns the path represented by [uri], which may be a [String] or a [Uri]. |
335 /// | 368 /// |
336 /// For POSIX and Windows styles, [uri] must be a `file:` URI. For the URL | 369 /// For POSIX and Windows styles, [uri] must be a `file:` URI. For the URL |
337 /// style, this will just convert [uri] to a string. | 370 /// style, this will just convert [uri] to a string. |
338 /// | 371 /// |
(...skipping 52 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
391 /// | 424 /// |
392 /// // Windows at "C:\root\path" | 425 /// // Windows at "C:\root\path" |
393 /// path.prettyUri('file:///C:/root/path/a/b.dart'); // -> r'a\b.dart' | 426 /// path.prettyUri('file:///C:/root/path/a/b.dart'); // -> r'a\b.dart' |
394 /// path.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org' | 427 /// path.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org' |
395 /// | 428 /// |
396 /// // URL at "http://dartlang.org/root/path" | 429 /// // URL at "http://dartlang.org/root/path" |
397 /// path.prettyUri('http://dartlang.org/root/path/a/b.dart'); | 430 /// path.prettyUri('http://dartlang.org/root/path/a/b.dart'); |
398 /// // -> r'a/b.dart' | 431 /// // -> r'a/b.dart' |
399 /// path.prettyUri('file:///root/path'); // -> 'file:///root/path' | 432 /// path.prettyUri('file:///root/path'); // -> 'file:///root/path' |
400 String prettyUri(uri) => context.prettyUri(uri); | 433 String prettyUri(uri) => context.prettyUri(uri); |
OLD | NEW |