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