| OLD | NEW |
|---|
| (Empty) |
| 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 | |
| 3 // BSD-style license that can be found in the LICENSE file. | |
| 4 | |
| 5 /// A comprehensive, cross-platform path manipulation library. | |
| 6 /// | |
| 7 /// ## Installing ## | |
| 8 /// | |
| 9 /// Use [pub][] to install this package. Add the following to your | |
| 10 /// `pubspec.yaml` file. | |
| 11 /// | |
| 12 /// dependencies: | |
| 13 /// path: any | |
| 14 /// | |
| 15 /// Then run `pub install`. | |
| 16 /// | |
| 17 /// For more information, see the [path package on pub.dartlang.org][pkg]. | |
| 18 /// | |
| 19 /// [pub]: http://pub.dartlang.org | |
| 20 /// [pkg]: http://pub.dartlang.org/packages/path | |
| 21 /// | |
| 22 /// ## Usage ## | |
| 23 /// | |
| 24 /// The path library was designed to be imported with a prefix, though you don't | |
| 25 /// have to if you don't want to: | |
| 26 /// | |
| 27 /// import 'package:path/path.dart' as path; | |
| 28 /// | |
| 29 /// The most common way to use the library is through the top-level functions. | |
| 30 /// These manipulate path strings based on your current working directory and | |
| 31 /// the path style (POSIX, Windows, or URLs) of the host platform. For example: | |
| 32 /// | |
| 33 /// path.join("directory", "file.txt"); | |
| 34 /// | |
| 35 /// This calls the top-level [join] function to join "directory" and "file.txt" | |
| 36 /// using the current platform's directory separator. | |
| 37 /// | |
| 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 | |
| 40 /// [Context] and give it an explicit [Style]: | |
| 41 /// | |
| 42 /// var context = new path.Context(style: Style.windows); | |
| 43 /// context.join("directory", "file.txt"); | |
| 44 /// | |
| 45 /// This will join "directory" and "file.txt" using the Windows path separator, | |
| 46 /// even when the program is run on a POSIX machine. | |
| 47 library path; | |
| 48 | |
| 49 import 'src/context.dart'; | |
| 50 import 'src/style.dart'; | |
| 51 | |
| 52 export 'src/context.dart' hide createInternal; | |
| 53 export 'src/path_exception.dart'; | |
| 54 export 'src/style.dart'; | |
| 55 | |
| 56 /// A default context for manipulating POSIX paths. | |
| 57 final Context posix = new Context(style: Style.posix); | |
| 58 | |
| 59 /// A default context for manipulating Windows paths. | |
| 60 final Context windows = new Context(style: Style.windows); | |
| 61 | |
| 62 /// A default context for manipulating URLs. | |
| 63 final Context url = new Context(style: Style.url); | |
| 64 | |
| 65 /// The system path context. | |
| 66 /// | |
| 67 /// 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 /// set once when the context is created. | |
| 70 final Context context = createInternal(); | |
| 71 | |
| 72 /// Returns the [Style] of the current context. | |
| 73 /// | |
| 74 /// This is the style that all top-level path functions will use. | |
| 75 Style get style => context.style; | |
| 76 | |
| 77 /// Gets the path to the current working directory. | |
| 78 /// | |
| 79 /// In the browser, this means the current URL, without the last file segment. | |
| 80 String get current { | |
| 81 var uri = Uri.base; | |
| 82 if (Style.platform == Style.url) { | |
| 83 return uri.resolve('.').toString(); | |
| 84 } else { | |
| 85 var path = uri.toFilePath(); | |
| 86 // Remove trailing '/' or '\'. | |
| 87 int lastIndex = path.length - 1; | |
| 88 assert(path[lastIndex] == '/' || path[lastIndex] == '\\'); | |
| 89 return path.substring(0, lastIndex); | |
| 90 } | |
| 91 } | |
| 92 | |
| 93 /// Gets the path separator for the current platform. This is `\` on Windows | |
| 94 /// and `/` on other platforms (including the browser). | |
| 95 String get separator => context.separator; | |
| 96 | |
| 97 /// Creates a new path by appending the given path parts to [current]. | |
| 98 /// Equivalent to [join()] with [current] as the first argument. Example: | |
| 99 /// | |
| 100 /// path.absolute('path', 'to/foo'); // -> '/your/current/dir/path/to/foo' | |
| 101 String absolute(String part1, [String part2, String part3, String part4, | |
| 102 String part5, String part6, String part7]) => | |
| 103 context.absolute(part1, part2, part3, part4, part5, part6, part7); | |
| 104 | |
| 105 /// Gets the part of [path] after the last separator. | |
| 106 /// | |
| 107 /// path.basename('path/to/foo.dart'); // -> 'foo.dart' | |
| 108 /// path.basename('path/to'); // -> 'to' | |
| 109 /// | |
| 110 /// Trailing separators are ignored. | |
| 111 /// | |
| 112 /// path.basename('path/to/'); // -> 'to' | |
| 113 String basename(String path) => context.basename(path); | |
| 114 | |
| 115 /// Gets the part of [path] after the last separator, and without any trailing | |
| 116 /// file extension. | |
| 117 /// | |
| 118 /// path.basenameWithoutExtension('path/to/foo.dart'); // -> 'foo' | |
| 119 /// | |
| 120 /// Trailing separators are ignored. | |
| 121 /// | |
| 122 /// path.basenameWithoutExtension('path/to/foo.dart/'); // -> 'foo' | |
| 123 String basenameWithoutExtension(String path) => | |
| 124 context.basenameWithoutExtension(path); | |
| 125 | |
| 126 /// Gets the part of [path] before the last separator. | |
| 127 /// | |
| 128 /// path.dirname('path/to/foo.dart'); // -> 'path/to' | |
| 129 /// path.dirname('path/to'); // -> 'path' | |
| 130 /// | |
| 131 /// Trailing separators are ignored. | |
| 132 /// | |
| 133 /// path.dirname('path/to/'); // -> 'path' | |
| 134 /// | |
| 135 /// If an absolute path contains no directories, only a root, then the root | |
| 136 /// is returned. | |
| 137 /// | |
| 138 /// path.dirname('/'); // -> '/' (posix) | |
| 139 /// path.dirname('c:\'); // -> 'c:\' (windows) | |
| 140 /// | |
| 141 /// If a relative path has no directories, then '.' is returned. | |
| 142 /// | |
| 143 /// path.dirname('foo'); // -> '.' | |
| 144 /// path.dirname(''); // -> '.' | |
| 145 String dirname(String path) => context.dirname(path); | |
| 146 | |
| 147 /// Gets the file extension of [path]: the portion of [basename] from the last | |
| 148 /// `.` to the end (including the `.` itself). | |
| 149 /// | |
| 150 /// path.extension('path/to/foo.dart'); // -> '.dart' | |
| 151 /// path.extension('path/to/foo'); // -> '' | |
| 152 /// path.extension('path.to/foo'); // -> '' | |
| 153 /// path.extension('path/to/foo.dart.js'); // -> '.js' | |
| 154 /// | |
| 155 /// If the file name starts with a `.`, then that is not considered the | |
| 156 /// extension: | |
| 157 /// | |
| 158 /// path.extension('~/.bashrc'); // -> '' | |
| 159 /// path.extension('~/.notes.txt'); // -> '.txt' | |
| 160 String extension(String path) => context.extension(path); | |
| 161 | |
| 162 // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed. | |
| 163 /// Returns the root of [path], if it's absolute, or the empty string if it's | |
| 164 /// relative. | |
| 165 /// | |
| 166 /// // Unix | |
| 167 /// path.rootPrefix('path/to/foo'); // -> '' | |
| 168 /// path.rootPrefix('/path/to/foo'); // -> '/' | |
| 169 /// | |
| 170 /// // Windows | |
| 171 /// path.rootPrefix(r'path\to\foo'); // -> '' | |
| 172 /// path.rootPrefix(r'C:\path\to\foo'); // -> r'C:\' | |
| 173 /// | |
| 174 /// // URL | |
| 175 /// path.rootPrefix('path/to/foo'); // -> '' | |
| 176 /// path.rootPrefix('http://dartlang.org/path/to/foo'); | |
| 177 /// // -> 'http://dartlang.org' | |
| 178 String rootPrefix(String path) => context.rootPrefix(path); | |
| 179 | |
| 180 /// Returns `true` if [path] is an absolute path and `false` if it is a | |
| 181 /// relative path. | |
| 182 /// | |
| 183 /// On POSIX systems, absolute paths start with a `/` (forward slash). On | |
| 184 /// Windows, an absolute path starts with `\\`, or a drive letter followed by | |
| 185 /// `:/` or `:\`. For URLs, absolute paths either start with a protocol and | |
| 186 /// optional hostname (e.g. `http://dartlang.org`, `file://`) or with a `/`. | |
| 187 /// | |
| 188 /// URLs that start with `/` are known as "root-relative", since they're | |
| 189 /// relative to the root of the current URL. Since root-relative paths are still | |
| 190 /// absolute in every other sense, [isAbsolute] will return true for them. They | |
| 191 /// can be detected using [isRootRelative]. | |
| 192 bool isAbsolute(String path) => context.isAbsolute(path); | |
| 193 | |
| 194 /// Returns `true` if [path] is a relative path and `false` if it is absolute. | |
| 195 /// On POSIX systems, absolute paths start with a `/` (forward slash). On | |
| 196 /// Windows, an absolute path starts with `\\`, or a drive letter followed by | |
| 197 /// `:/` or `:\`. | |
| 198 bool isRelative(String path) => context.isRelative(path); | |
| 199 | |
| 200 /// Returns `true` if [path] is a root-relative path and `false` if it's not. | |
| 201 /// | |
| 202 /// URLs that start with `/` are known as "root-relative", since they're | |
| 203 /// relative to the root of the current URL. Since root-relative paths are still | |
| 204 /// absolute in every other sense, [isAbsolute] will return true for them. They | |
| 205 /// can be detected using [isRootRelative]. | |
| 206 /// | |
| 207 /// No POSIX and Windows paths are root-relative. | |
| 208 bool isRootRelative(String path) => context.isRootRelative(path); | |
| 209 | |
| 210 /// Joins the given path parts into a single path using the current platform's | |
| 211 /// [separator]. Example: | |
| 212 /// | |
| 213 /// path.join('path', 'to', 'foo'); // -> 'path/to/foo' | |
| 214 /// | |
| 215 /// If any part ends in a path separator, then a redundant separator will not | |
| 216 /// be added: | |
| 217 /// | |
| 218 /// path.join('path/', 'to', 'foo'); // -> 'path/to/foo | |
| 219 /// | |
| 220 /// If a part is an absolute path, then anything before that will be ignored: | |
| 221 /// | |
| 222 /// path.join('path', '/to', 'foo'); // -> '/to/foo' | |
| 223 String join(String part1, [String part2, String part3, String part4, | |
| 224 String part5, String part6, String part7, String part8]) => | |
| 225 context.join(part1, part2, part3, part4, part5, part6, part7, part8); | |
| 226 | |
| 227 /// Joins the given path parts into a single path using the current platform's | |
| 228 /// [separator]. Example: | |
| 229 /// | |
| 230 /// path.joinAll(['path', 'to', 'foo']); // -> 'path/to/foo' | |
| 231 /// | |
| 232 /// If any part ends in a path separator, then a redundant separator will not | |
| 233 /// be added: | |
| 234 /// | |
| 235 /// path.joinAll(['path/', 'to', 'foo']); // -> 'path/to/foo | |
| 236 /// | |
| 237 /// If a part is an absolute path, then anything before that will be ignored: | |
| 238 /// | |
| 239 /// path.joinAll(['path', '/to', 'foo']); // -> '/to/foo' | |
| 240 /// | |
| 241 /// For a fixed number of parts, [join] is usually terser. | |
| 242 String joinAll(Iterable<String> parts) => context.joinAll(parts); | |
| 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 [separator]. | |
| 246 /// | |
| 247 /// path.split('path/to/foo'); // -> ['path', 'to', 'foo'] | |
| 248 /// | |
| 249 /// The path will *not* be normalized before splitting. | |
| 250 /// | |
| 251 /// path.split('path/../foo'); // -> ['path', '..', 'foo'] | |
| 252 /// | |
| 253 /// If [path] is absolute, the root directory will be the first element in the | |
| 254 /// array. Example: | |
| 255 /// | |
| 256 /// // Unix | |
| 257 /// path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo'] | |
| 258 /// | |
| 259 /// // Windows | |
| 260 /// path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo'] | |
| 261 /// | |
| 262 /// // Browser | |
| 263 /// path.split('http://dartlang.org/path/to/foo'); | |
| 264 /// // -> ['http://dartlang.org', 'path', 'to', 'foo'] | |
| 265 List<String> split(String path) => context.split(path); | |
| 266 | |
| 267 /// Normalizes [path], simplifying it by handling `..`, and `.`, and | |
| 268 /// removing redundant path separators whenever possible. | |
| 269 /// | |
| 270 /// path.normalize('path/./to/..//file.text'); // -> 'path/file.txt' | |
| 271 String normalize(String path) => context.normalize(path); | |
| 272 | |
| 273 /// Attempts to convert [path] to an equivalent relative path from the current | |
| 274 /// directory. | |
| 275 /// | |
| 276 /// // Given current directory is /root/path: | |
| 277 /// path.relative('/root/path/a/b.dart'); // -> 'a/b.dart' | |
| 278 /// path.relative('/root/other.dart'); // -> '../other.dart' | |
| 279 /// | |
| 280 /// If the [from] argument is passed, [path] is made relative to that instead. | |
| 281 /// | |
| 282 /// path.relative('/root/path/a/b.dart', | |
| 283 /// from: '/root/path'); // -> 'a/b.dart' | |
| 284 /// path.relative('/root/other.dart', | |
| 285 /// from: '/root/path'); // -> '../other.dart' | |
| 286 /// | |
| 287 /// If [path] and/or [from] are relative paths, they are assumed to be relative | |
| 288 /// to the current directory. | |
| 289 /// | |
| 290 /// Since there is no relative path from one drive letter to another on Windows, | |
| 291 /// or from one hostname to another for URLs, this will return an absolute path | |
| 292 /// in those cases. | |
| 293 /// | |
| 294 /// // Windows | |
| 295 /// path.relative(r'D:\other', from: r'C:\home'); // -> 'D:\other' | |
| 296 /// | |
| 297 /// // URL | |
| 298 /// path.relative('http://dartlang.org', from: 'http://pub.dartlang.org'); | |
| 299 /// // -> 'http://dartlang.org' | |
| 300 String relative(String path, {String from}) => | |
| 301 context.relative(path, from: from); | |
| 302 | |
| 303 /// Returns `true` if [child] is a path beneath `parent`, and `false` otherwise. | |
| 304 /// | |
| 305 /// path.isWithin('/root/path', '/root/path/a'); // -> true | |
| 306 /// path.isWithin('/root/path', '/root/other'); // -> false | |
| 307 /// path.isWithin('/root/path', '/root/path') // -> false | |
| 308 bool isWithin(String parent, String child) => context.isWithin(parent, child); | |
| 309 | |
| 310 /// Removes a trailing extension from the last part of [path]. | |
| 311 /// | |
| 312 /// withoutExtension('path/to/foo.dart'); // -> 'path/to/foo' | |
| 313 String withoutExtension(String path) => context.withoutExtension(path); | |
| 314 | |
| 315 /// Returns the path represented by [uri], which may be a [String] or a [Uri]. | |
| 316 /// | |
| 317 /// For POSIX and Windows styles, [uri] must be a `file:` URI. For the URL | |
| 318 /// style, this will just convert [uri] to a string. | |
| 319 /// | |
| 320 /// // POSIX | |
| 321 /// context.fromUri('file:///path/to/foo') | |
| 322 /// // -> '/path/to/foo' | |
| 323 /// | |
| 324 /// // Windows | |
| 325 /// context.fromUri('file:///C:/path/to/foo') | |
| 326 /// // -> r'C:\path\to\foo' | |
| 327 /// | |
| 328 /// // URL | |
| 329 /// context.fromUri('http://dartlang.org/path/to/foo') | |
| 330 /// // -> 'http://dartlang.org/path/to/foo' | |
| 331 /// | |
| 332 /// If [uri] is relative, a relative path will be returned. | |
| 333 /// | |
| 334 /// path.fromUri('path/to/foo'); // -> 'path/to/foo' | |
| 335 String fromUri(uri) => context.fromUri(uri); | |
| 336 | |
| 337 /// Returns the URI that represents [path]. | |
| 338 /// | |
| 339 /// For POSIX and Windows styles, this will return a `file:` URI. For the URL | |
| 340 /// style, this will just convert [path] to a [Uri]. | |
| 341 /// | |
| 342 /// // POSIX | |
| 343 /// path.toUri('/path/to/foo') | |
| 344 /// // -> Uri.parse('file:///path/to/foo') | |
| 345 /// | |
| 346 /// // Windows | |
| 347 /// path.toUri(r'C:\path\to\foo') | |
| 348 /// // -> Uri.parse('file:///C:/path/to/foo') | |
| 349 /// | |
| 350 /// // URL | |
| 351 /// path.toUri('http://dartlang.org/path/to/foo') | |
| 352 /// // -> Uri.parse('http://dartlang.org/path/to/foo') | |
| 353 /// | |
| 354 /// If [path] is relative, a relative URI will be returned. | |
| 355 /// | |
| 356 /// path.toUri('path/to/foo') | |
| 357 /// // -> Uri.parse('path/to/foo') | |
| 358 Uri toUri(String path) => context.toUri(path); | |
| 359 | |
| 360 /// Returns a terse, human-readable representation of [uri]. | |
| 361 /// | |
| 362 /// [uri] can be a [String] or a [Uri]. If it can be made relative to the | |
| 363 /// current working directory, that's done. Otherwise, it's returned as-is. This | |
| 364 /// gracefully handles non-`file:` URIs for [Style.posix] and [Style.windows]. | |
| 365 /// | |
| 366 /// The returned value is meant for human consumption, and may be either URI- | |
| 367 /// or path-formatted. | |
| 368 /// | |
| 369 /// // POSIX at "/root/path" | |
| 370 /// path.prettyUri('file:///root/path/a/b.dart'); // -> 'a/b.dart' | |
| 371 /// path.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org' | |
| 372 /// | |
| 373 /// // Windows at "C:\root\path" | |
| 374 /// path.prettyUri('file:///C:/root/path/a/b.dart'); // -> r'a\b.dart' | |
| 375 /// path.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org' | |
| 376 /// | |
| 377 /// // URL at "http://dartlang.org/root/path" | |
| 378 /// path.prettyUri('http://dartlang.org/root/path/a/b.dart'); | |
| 379 /// // -> r'a/b.dart' | |
| 380 /// path.prettyUri('file:///root/path'); // -> 'file:///root/path' | |
| 381 String prettyUri(uri) => context.prettyUri(uri); | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 1400473008:
Roll Observatory packages and add a roll script (Closed)
Base URL: git@github.com:dart-lang/observatory_pub_packages.git@master