Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(252)

Side by Side Diff: pkg/path/README.md

Issue 12047035: Add a README for path. (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Revised. Created 7 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
« no previous file with comments | « no previous file | pkg/path/lib/path.dart » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(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.
OLDNEW
« no previous file with comments | « no previous file | pkg/path/lib/path.dart » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698