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 |