| OLD | NEW |
| 1 A comprehensive, cross-platform path manipulation library for Dart. | 1 A comprehensive, cross-platform path manipulation library for Dart. |
| 2 | 2 |
| 3 The path package provides common operations for manipulating paths: | 3 The path package provides common operations for manipulating paths: |
| 4 joining, splitting, normalizing, etc. | 4 joining, splitting, normalizing, etc. |
| 5 | 5 |
| 6 We've tried very hard to make this library do the "right" thing on whatever | 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 | 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 | 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 | 9 that. If you want to explicitly work with paths of a specific style, you can |
| 10 construct a `path.Context` for that style. | 10 construct a `path.Context` for that style. |
| (...skipping 23 matching lines...) Expand all Loading... |
| 34 [Context] and give it an explicit [Style]: | 34 [Context] and give it an explicit [Style]: |
| 35 | 35 |
| 36 ```dart | 36 ```dart |
| 37 var context = new path.Context(style: Style.windows); | 37 var context = new path.Context(style: Style.windows); |
| 38 context.join("directory", "file.txt"); | 38 context.join("directory", "file.txt"); |
| 39 ``` | 39 ``` |
| 40 | 40 |
| 41 This will join "directory" and "file.txt" using the Windows path separator, | 41 This will join "directory" and "file.txt" using the Windows path separator, |
| 42 even when the program is run on a POSIX machine. | 42 even when the program is run on a POSIX machine. |
| 43 | 43 |
| 44 ## Stability |
| 45 |
| 46 The `path` package is used by many Dart packages, and as such it strives for a |
| 47 very high degree of stability. For the same reason, though, releasing a new |
| 48 major version would probably cause a lot of versioning pain, so some flexibility |
| 49 is necessary. |
| 50 |
| 51 We try to guarantee that **operations with valid inputs and correct output will |
| 52 not change**. Operations where one or more inputs are invalid according to the |
| 53 semantics of the corresponding platform may produce different output over time. |
| 54 Operations for which `path` produces incorrect output will also change so that |
| 55 we can fix bugs. |
| 56 |
| 57 Also, the `path` package's URL handling is based on [the WHATWG URL spec][]. |
| 58 This is a living standard, and some parts of it haven't yet been entirely |
| 59 solidified by vendor support. The `path` package reserves the right to change |
| 60 its URL behavior if the underlying specification changes, although if the change |
| 61 is big enough to break many valid uses we may elect to treat it as a breaking |
| 62 change anyway. |
| 63 |
| 64 [the WHATWG URL spec]: https://url.spec.whatwg.org/ |
| 65 |
| 44 ## FAQ | 66 ## FAQ |
| 45 | 67 |
| 46 ### Where can I use this? | 68 ### Where can I use this? |
| 47 | 69 |
| 48 Pathos runs on the Dart VM and in the browser under both dart2js and Dartium. | 70 The `path` package runs on the Dart VM and in the browser under both dart2js and |
| 49 Under dart2js, it currently returns "." as the current working directory, while | 71 Dartium. On the browser, `window.location.href` is used as the current path. |
| 50 under Dartium it returns the current URL. | |
| 51 | 72 |
| 52 ### Why doesn't this make paths first-class objects? | 73 ### Why doesn't this make paths first-class objects? |
| 53 | 74 |
| 54 When you have path *objects*, then every API that takes a path has to decide if | 75 When you have path *objects*, then every API that takes a path has to decide if |
| 55 it accepts strings, path objects, or both. | 76 it accepts strings, path objects, or both. |
| 56 | 77 |
| 57 * Accepting strings is the most convenient, but then it seems weird to have | 78 * 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 | 79 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 | 80 path. Once you've created a path, you have to always call `.toString()` on |
| 60 it before you can do anything useful with it. | 81 it before you can do anything useful with it. |
| (...skipping 23 matching lines...) Expand all Loading... |
| 84 | 105 |
| 85 * It understands that "/foo" is not an absolute path on Windows. | 106 * It understands that "/foo" is not an absolute path on Windows. |
| 86 | 107 |
| 87 * It knows that "C:\foo\one.txt" and "c:/foo\two.txt" are two files in the | 108 * It knows that "C:\foo\one.txt" and "c:/foo\two.txt" are two files in the |
| 88 same directory. | 109 same directory. |
| 89 | 110 |
| 90 ### What is a "path" in the browser? | 111 ### What is a "path" in the browser? |
| 91 | 112 |
| 92 If you use this package in a browser, then it considers the "platform" to be | 113 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". | 114 the browser itself and uses URL strings to represent "browser paths". |
| OLD | NEW |