| 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 | |
| 8 the host OS's path style and work with that. If you want to specifically work | |
| 9 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 or Windows) of the host operating system. | |
| 24 | |
| 25 ### String get current | |
| 26 | |
| 27 Gets the path to the current working directory. | |
| 28 | |
| 29 ### String get separator | |
| 30 | |
| 31 Gets the path separator for the current platform. On Mac and Linux, this | |
| 32 is `/`. On Windows, it's `\`. | |
| 33 | |
| 34 ### String absolute(String path) | |
| 35 | |
| 36 Converts [path] to an absolute path by resolving it relative to the current | |
| 37 working directory. If [path] is already an absolute path, just returns it. | |
| 38 | |
| 39 path.absolute('foo/bar.txt'); // -> /your/current/dir/foo/bar.txt | |
| 40 | |
| 41 ### String basename(String path) | |
| 42 | |
| 43 Gets the part of [path] after the last separator. | |
| 44 | |
| 45 path.basename('path/to/foo.dart'); // -> 'foo.dart' | |
| 46 path.basename('path/to'); // -> 'to' | |
| 47 | |
| 48 Trailing separators are ignored. | |
| 49 | |
| 50 builder.basename('path/to/'); // -> 'to' | |
| 51 | |
| 52 ### String basenameWithoutExtension(String path) | |
| 53 | |
| 54 Gets the part of [path] after the last separator, and without any trailing | |
| 55 file extension. | |
| 56 | |
| 57 path.basenameWithoutExtension('path/to/foo.dart'); // -> 'foo' | |
| 58 | |
| 59 Trailing separators are ignored. | |
| 60 | |
| 61 builder.basenameWithoutExtension('path/to/foo.dart/'); // -> 'foo' | |
| 62 | |
| 63 ### String dirname(String path) | |
| 64 | |
| 65 Gets the part of [path] before the last separator. | |
| 66 | |
| 67 path.dirname('path/to/foo.dart'); // -> 'path/to' | |
| 68 path.dirname('path/to'); // -> 'to' | |
| 69 | |
| 70 Trailing separators are ignored. | |
| 71 | |
| 72 builder.dirname('path/to/'); // -> 'path' | |
| 73 | |
| 74 ### String extension(String path) | |
| 75 | |
| 76 Gets the file extension of [path]: the portion of [basename] from the last | |
| 77 `.` to the end (including the `.` itself). | |
| 78 | |
| 79 path.extension('path/to/foo.dart'); // -> '.dart' | |
| 80 path.extension('path/to/foo'); // -> '' | |
| 81 path.extension('path.to/foo'); // -> '' | |
| 82 path.extension('path/to/foo.dart.js'); // -> '.js' | |
| 83 | |
| 84 If the file name starts with a `.`, then that is not considered the | |
| 85 extension: | |
| 86 | |
| 87 path.extension('~/.bashrc'); // -> '' | |
| 88 path.extension('~/.notes.txt'); // -> '.txt' | |
| 89 | |
| 90 ### String rootPrefix(String path) | |
| 91 | |
| 92 Returns the root of [path], if it's absolute, or the empty string if it's | |
| 93 relative. | |
| 94 | |
| 95 // Unix | |
| 96 path.rootPrefix('path/to/foo'); // -> '' | |
| 97 path.rootPrefix('/path/to/foo'); // -> '/' | |
| 98 | |
| 99 // Windows | |
| 100 path.rootPrefix(r'path\to\foo'); // -> '' | |
| 101 path.rootPrefix(r'C:\path\to\foo'); // -> r'C:\' | |
| 102 | |
| 103 ### bool isAbsolute(String path) | |
| 104 | |
| 105 Returns `true` if [path] is an absolute path and `false` if it is a | |
| 106 relative path. On POSIX systems, absolute paths start with a `/` (forward | |
| 107 slash). On Windows, an absolute path starts with `\\`, or a drive letter | |
| 108 followed by `:/` or `:\`. | |
| 109 | |
| 110 ### bool isRelative(String path) | |
| 111 | |
| 112 Returns `true` if [path] is a relative path and `false` if it is absolute. | |
| 113 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 `:\`. | |
| 116 | |
| 117 ### String join(String part1, [String part2, String part3, ...]) | |
| 118 | |
| 119 Joins the given path parts into a single path using the current platform's | |
| 120 [separator]. Example: | |
| 121 | |
| 122 path.join('path', 'to', 'foo'); // -> 'path/to/foo' | |
| 123 | |
| 124 If any part ends in a path separator, then a redundant separator will not | |
| 125 be added: | |
| 126 | |
| 127 path.join('path/', 'to', 'foo'); // -> 'path/to/foo | |
| 128 | |
| 129 If a part is an absolute path, then anything before that will be ignored: | |
| 130 | |
| 131 path.join('path', '/to', 'foo'); // -> '/to/foo' | |
| 132 | |
| 133 ### List<String> split(String path) | |
| 134 | |
| 135 Splits [path] into its components using the current platform's [separator]. | |
| 136 | |
| 137 path.split('path/to/foo'); // -> ['path', 'to', 'foo'] | |
| 138 | |
| 139 The path will *not* be normalized before splitting. | |
| 140 | |
| 141 path.split('path/../foo'); // -> ['path', '..', 'foo'] | |
| 142 | |
| 143 If [path] is absolute, the root directory will be the first element in the | |
| 144 array. Example: | |
| 145 | |
| 146 // Unix | |
| 147 path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo'] | |
| 148 | |
| 149 // Windows | |
| 150 path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo'] | |
| 151 | |
| 152 ### String normalize(String path) | |
| 153 | |
| 154 Normalizes [path], simplifying it by handling `..`, and `.`, and | |
| 155 removing redundant path separators whenever possible. | |
| 156 | |
| 157 path.normalize('path/./to/..//file.text'); // -> 'path/file.txt' | |
| 158 String normalize(String path) => _builder.normalize(path); | |
| 159 | |
| 160 ### String relative(String path, {String from}) | |
| 161 | |
| 162 Attempts to convert [path] to an equivalent relative path from the current | |
| 163 directory. | |
| 164 | |
| 165 // Given current directory is /root/path: | |
| 166 path.relative('/root/path/a/b.dart'); // -> 'a/b.dart' | |
| 167 path.relative('/root/other.dart'); // -> '../other.dart' | |
| 168 | |
| 169 If the [from] argument is passed, [path] is made relative to that instead. | |
| 170 | |
| 171 path.relative('/root/path/a/b.dart', | |
| 172 from: '/root/path'); // -> 'a/b.dart' | |
| 173 path.relative('/root/other.dart', | |
| 174 from: '/root/path'); // -> '../other.dart' | |
| 175 | |
| 176 Since there is no relative path from one drive letter to another on Windows, | |
| 177 this will return an absolute path in that case. | |
| 178 | |
| 179 path.relative(r'D:\other', from: r'C:\home'); // -> 'D:\other' | |
| 180 | |
| 181 ### String withoutExtension(String path) | |
| 182 | |
| 183 Removes a trailing extension from the last part of [path]. | |
| 184 | |
| 185 withoutExtension('path/to/foo.dart'); // -> 'path/to/foo' | |
| 186 | |
| 187 ## The path.Builder class | |
| 188 | |
| 189 In addition to the functions, path exposes a `path.Builder` class. This lets | |
| 190 you configure the root directory and path style that paths are built using | |
| 191 explicitly instead of assuming the current working directory and host OS's path | |
| 192 style. | |
| 193 | |
| 194 You won't often use this, but it can be useful if you do a lot of path | |
| 195 manipulation relative to some root directory. | |
| 196 | |
| 197 var builder = new path.Builder(root: '/other/root'); | |
| 198 builder.relative('/other/root/foo.txt'); // -> 'foo.txt' | |
| 199 | |
| 200 It exposes the same methods and getters as the top-level functions, with the | |
| 201 addition of: | |
| 202 | |
| 203 ### new Builder({Style style, String root}) | |
| 204 | |
| 205 Creates a new path builder for the given style and root directory. | |
| 206 | |
| 207 If [style] is omitted, it uses the host operating system's path style. If | |
| 208 [root] is omitted, it defaults to the current working directory. If [root] | |
| 209 is relative, it is considered relative to the current working directory. | |
| 210 | |
| 211 ### Style style | |
| 212 | |
| 213 The style of path that this builder works with. | |
| 214 | |
| 215 ### String root | |
| 216 | |
| 217 The root directory that relative paths will be relative to. | |
| 218 | |
| 219 ### String get separator | |
| 220 | |
| 221 Gets the path separator for the builder's [style]. On Mac and Linux, | |
| 222 this is `/`. On Windows, it's `\`. | |
| 223 | |
| 224 ### String rootPrefix(String path) | |
| 225 | |
| 226 Returns the root of [path], if it's absolute, or an empty string if it's | |
| 227 relative. | |
| 228 | |
| 229 // Unix | |
| 230 builder.rootPrefix('path/to/foo'); // -> '' | |
| 231 builder.rootPrefix('/path/to/foo'); // -> '/' | |
| 232 | |
| 233 // Windows | |
| 234 builder.rootPrefix(r'path\to\foo'); // -> '' | |
| 235 builder.rootPrefix(r'C:\path\to\foo'); // -> r'C:\' | |
| 236 | |
| 237 ### String resolve(String part1, [String part2, String part3, ...]) | |
| 238 | |
| 239 Creates a new path by appending the given path parts to the [root]. | |
| 240 Equivalent to [join()] with [root] as the first argument. Example: | |
| 241 | |
| 242 var builder = new Builder(root: 'root'); | |
| 243 builder.resolve('path', 'to', 'foo'); // -> 'root/path/to/foo' | |
| 244 | |
| 245 ## The path.Style class | |
| 246 | |
| 247 The path library can work with two different "flavors" of path: POSIX and | |
| 248 Windows. The differences between these are encapsulated by the `path.Style` | |
| 249 enum class. There are two instances of it: | |
| 250 | |
| 251 ### path.Style.posix | |
| 252 | |
| 253 POSIX-style paths use "/" (forward slash) as separators. Absolute paths | |
| 254 start with "/". Used by UNIX, Linux, Mac OS X, and others. | |
| 255 | |
| 256 ### path.Style.windows | |
| 257 | |
| 258 Windows paths use "\" (backslash) as separators. Absolute paths start with | |
| 259 a drive letter followed by a colon (example, "C:") or two backslashes | |
| 260 ("\\") for UNC paths. | |
| 261 | |
| 262 ## FAQ | |
| 263 | |
| 264 ### Where can I use this? | |
| 265 | |
| 266 Currently, Dart has no way of encapsulating configuration-specific code. | |
| 267 Ideally, this library would be able to import dart:io when that's available or | |
| 268 dart:html when that is. That would let it seamlessly work on both. | |
| 269 | |
| 270 Until then, this only works on the standalone VM. It's API is not coupled to | |
| 271 dart:io, but it uses it internally to determine the current working directory. | |
| 272 | |
| 273 ### Why doesn't this make paths first-class objects? | |
| 274 | |
| 275 When you have path *objects*, then every API that takes a path has to decide if | |
| 276 it accepts strings, path objects, or both. | |
| 277 | |
| 278 * Accepting strings is the most convenient, but then it seems weird to have | |
| 279 these path objects that aren't actually accepted by anything that needs a | |
| 280 path. Once you've created a path, you have to always call `.toString()` on | |
| 281 it before you can do anything useful with it. | |
| 282 | |
| 283 * Requiring objects forces users to wrap path strings in these objects, which | |
| 284 is tedious. It also means coupling that API to whatever library defines this | |
| 285 path class. If there are multiple "path" libraries that each define their | |
| 286 own path types, then any library that works with paths has to pick which one | |
| 287 it uses. | |
| 288 | |
| 289 * Taking both means you can't type your API. That defeats the purpose of | |
| 290 having a path type: why have a type if your APIs can't annotate that they | |
| 291 use it? | |
| 292 | |
| 293 Given that, we've decided this library should simply treat paths as strings. | |
| 294 | |
| 295 ### How cross-platform is this? | |
| 296 | |
| 297 We believe this library handles most of the corner cases of Windows paths | |
| 298 (POSIX paths are generally pretty straightforward): | |
| 299 | |
| 300 * It understands that *both* "/" and "\" are valid path separators, not just | |
| 301 "\". | |
| 302 | |
| 303 * It can accurately tell if a path is absolute based on drive-letters or UNC | |
| 304 prefix. | |
| 305 | |
| 306 * It understands that "/foo" is not an absolute path on Windows. | |
| 307 | |
| 308 * It knows that "C:\foo\one.txt" and "c:/foo\two.txt" are two files in the | |
| 309 same directory. | |
| 310 | |
| 311 If you find a problem, surprise or something that's unclear, please don't | |
| 312 hesitate to [file a bug](http://dartbug.com/new) and let us know. | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 12316056:
Move pkg/path to pkg/pathos. (Closed)
Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart