OLD | NEW |
(Empty) | |
| 1 A comprehensive, cross-platform path manipulation library for Dart. |
| 2 |
| 3 The path package provides common operations for manipulating 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, including in the browser. When you use the top-level |
| 8 functions, it will assume the current platform's path style and work with |
| 9 that. If you want to explicitly work with paths of a specific style, you can |
| 10 construct a `path.Context` for that 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 ```dart |
| 18 import 'package:path/path.dart' as path; |
| 19 ``` |
| 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 |
| 23 the path style (POSIX, Windows, or URLs) of the host platform. For example: |
| 24 |
| 25 ```dart |
| 26 path.join("directory", "file.txt"); |
| 27 ``` |
| 28 |
| 29 This calls the top-level [join] function to join "directory" and |
| 30 "file.txt" using the current platform's directory separator. |
| 31 |
| 32 If you want to work with paths for a specific platform regardless of the |
| 33 underlying platform that the program is running on, you can create a |
| 34 [Context] and give it an explicit [Style]: |
| 35 |
| 36 ```dart |
| 37 var context = new path.Context(style: Style.windows); |
| 38 context.join("directory", "file.txt"); |
| 39 ``` |
| 40 |
| 41 This will join "directory" and "file.txt" using the Windows path separator, |
| 42 even when the program is run on a POSIX machine. |
| 43 |
| 44 ## FAQ |
| 45 |
| 46 ### Where can I use this? |
| 47 |
| 48 Pathos runs on the Dart VM and in the browser under both dart2js and Dartium. |
| 49 Under dart2js, it currently returns "." as the current working directory, while |
| 50 under Dartium it returns the current URL. |
| 51 |
| 52 ### Why doesn't this make paths first-class objects? |
| 53 |
| 54 When you have path *objects*, then every API that takes a path has to decide if |
| 55 it accepts strings, path objects, or both. |
| 56 |
| 57 * Accepting strings is the most convenient, but then it seems weird to have |
| 58 these path objects that aren't actually accepted by anything that needs a |
| 59 path. Once you've created a path, you have to always call `.toString()` on |
| 60 it before you can do anything useful with it. |
| 61 |
| 62 * Requiring objects forces users to wrap path strings in these objects, which |
| 63 is tedious. It also means coupling that API to whatever library defines this |
| 64 path class. If there are multiple "path" libraries that each define their |
| 65 own path types, then any library that works with paths has to pick which one |
| 66 it uses. |
| 67 |
| 68 * Taking both means you can't type your API. That defeats the purpose of |
| 69 having a path type: why have a type if your APIs can't annotate that they |
| 70 expect it? |
| 71 |
| 72 Given that, we've decided this library should simply treat paths as strings. |
| 73 |
| 74 ### How cross-platform is this? |
| 75 |
| 76 We believe this library handles most of the corner cases of Windows paths |
| 77 (POSIX paths are generally pretty straightforward): |
| 78 |
| 79 * It understands that *both* "/" and "\" are valid path separators, not just |
| 80 "\". |
| 81 |
| 82 * It can accurately tell if a path is absolute based on drive-letters or UNC |
| 83 prefix. |
| 84 |
| 85 * It understands that "/foo" is not an absolute path on Windows. |
| 86 |
| 87 * It knows that "C:\foo\one.txt" and "c:/foo\two.txt" are two files in the |
| 88 same directory. |
| 89 |
| 90 ### What is a "path" in the browser? |
| 91 |
| 92 If you use this package in a browser, then it considers the "platform" to be |
| 93 the browser itself and uses URL strings to represent "browser paths". |
OLD | NEW |