OLD | NEW |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 part of dart.io; | 5 part of dart.io; |
6 | 6 |
7 /** | 7 /** |
8 * A Path is an immutable wrapper of a String, with additional member functions | 8 * A Path is an immutable wrapper of a String, with additional member functions |
9 * for useful path manipulations and queries. | 9 * for useful path manipulations and queries. |
10 * On the Windows platform, Path also converts from native paths to paths using | 10 * On the Windows platform, Path also converts from native paths to paths using |
11 * '/' as a path separator, and vice versa. | 11 * '/' as a path separator, and vice versa. |
12 * | 12 * |
13 * Joining of paths and path normalization handle '.' and '..' in the usual way. | 13 * Joining of paths and path normalization handle '.' and '..' in the usual way. |
14 * | 14 * |
15 * *Path is deprecated. Use package path. Path will be removed the 11th of | 15 * *Path is deprecated. Use package path. Path will be removed the 11th of |
16 * August 2013.* | 16 * August 2013.* |
17 */ | 17 */ |
18 @deprecated | 18 @deprecated |
19 abstract class Path { | 19 abstract class _Path { |
20 /** | 20 /** |
21 * Creates a Path from a String that uses the native filesystem's conventions. | 21 * Creates a Path from a String that uses the native filesystem's conventions. |
22 * | 22 * |
23 * On Windows, this converts '\' to '/' and has special handling for drive | 23 * On Windows, this converts '\' to '/' and has special handling for drive |
24 * letters and shares. | 24 * letters and shares. |
25 * | 25 * |
26 * If the path starts with a drive letter, like 'C:', a '/' is added | 26 * If the path starts with a drive letter, like 'C:', a '/' is added |
27 * before the drive letter. | 27 * before the drive letter. |
28 * | 28 * |
29 * new Path(r'c:\a\b').toString() == '/c:/a/b' | 29 * new _Path(r'c:\a\b').toString() == '/c:/a/b' |
30 * | 30 * |
31 * A path starting with a drive letter is | 31 * A path starting with a drive letter is |
32 * treated specially. Backwards links ('..') cannot cancel the drive letter. | 32 * treated specially. Backwards links ('..') cannot cancel the drive letter. |
33 * | 33 * |
34 * If the path is a share path this is recorded in the Path object and | 34 * If the path is a share path this is recorded in the Path object and |
35 * maintained in operations on the Path object. | 35 * maintained in operations on the Path object. |
36 * | 36 * |
37 * var share = new Path(r'\\share\a\b\c'); | 37 * var share = new _Path(r'\\share\a\b\c'); |
38 * share.isWindowsShare == true | 38 * share.isWindowsShare == true |
39 * share.toString() == '/share/a/b/c' | 39 * share.toString() == '/share/a/b/c' |
40 * share.toNativePath() == r'\\share\a\b\c' | 40 * share.toNativePath() == r'\\share\a\b\c' |
41 * share.append('final').isWindowsShare == true | 41 * share.append('final').isWindowsShare == true |
42 */ | 42 */ |
43 @deprecated | 43 @deprecated |
44 factory Path(String source) => new _Path(source); | 44 factory _Path(String source) => new __Path(source); |
45 | 45 |
46 /** | 46 /** |
47 * Creates a Path from the String [source]. [source] is used as-is, so if | 47 * Creates a Path from the String [source]. [source] is used as-is, so if |
48 * the string does not consist of segments separated by forward slashes, the | 48 * the string does not consist of segments separated by forward slashes, the |
49 * behavior may not be as expected. Paths are immutable. | 49 * behavior may not be as expected. Paths are immutable. |
50 */ | 50 */ |
51 @deprecated | 51 @deprecated |
52 factory Path.raw(String source) => new _Path.raw(source); | 52 factory _Path.raw(String source) => new __Path.raw(source); |
53 | 53 |
54 /** | 54 /** |
55 * Is this path the empty string? | 55 * Is this path the empty string? |
56 */ | 56 */ |
57 bool get isEmpty; | 57 bool get isEmpty; |
58 | 58 |
59 /** | 59 /** |
60 * Is this path an absolute path, beginning with a '/'? Note that | 60 * Is this path an absolute path, beginning with a '/'? Note that |
61 * Windows paths beginning with '\' or with a drive letter are absolute, | 61 * Windows paths beginning with '\' or with a drive letter are absolute, |
62 * and a leading '/' is added when they are converted to a Path. | 62 * and a leading '/' is added when they are converted to a Path. |
(...skipping 16 matching lines...) Expand all Loading... |
79 * as the leading segments on a relative path? | 79 * as the leading segments on a relative path? |
80 */ | 80 */ |
81 bool get isCanonical; | 81 bool get isCanonical; |
82 | 82 |
83 /** | 83 /** |
84 * Make a path canonical by dropping segments that are '.', cancelling | 84 * Make a path canonical by dropping segments that are '.', cancelling |
85 * segments that are '..' with preceding segments, if possible, | 85 * segments that are '..' with preceding segments, if possible, |
86 * and combining consecutive '/'s. Leading '..' segments | 86 * and combining consecutive '/'s. Leading '..' segments |
87 * are kept on relative paths, and dropped from absolute paths. | 87 * are kept on relative paths, and dropped from absolute paths. |
88 */ | 88 */ |
89 Path canonicalize(); | 89 _Path canonicalize(); |
90 | 90 |
91 /** | 91 /** |
92 * Joins the relative path [further] to this path. Canonicalizes the | 92 * Joins the relative path [further] to this path. Canonicalizes the |
93 * resulting joined path using [canonicalize], | 93 * resulting joined path using [canonicalize], |
94 * interpreting '.' and '..' as directory traversal commands, and removing | 94 * interpreting '.' and '..' as directory traversal commands, and removing |
95 * consecutive '/'s. | 95 * consecutive '/'s. |
96 * | 96 * |
97 * If [further] is an absolute path, an IllegalArgument exception is thrown. | 97 * If [further] is an absolute path, an IllegalArgument exception is thrown. |
98 * | 98 * |
99 * Examples: | 99 * Examples: |
100 * `new Path('/a/b/c').join(new Path('d/e'))` returns the Path object | 100 * `new _Path('/a/b/c').join(new _Path('d/e'))` returns the Path object |
101 * containing `'a/b/c/d/e'`. | 101 * containing `'a/b/c/d/e'`. |
102 * | 102 * |
103 * `new Path('a/b/../c/').join(new Path('d/./e//')` returns the Path | 103 * `new _Path('a/b/../c/').join(new _Path('d/./e//')` returns the Path |
104 * containing `'a/c/d/e/'`. | 104 * containing `'a/c/d/e/'`. |
105 * | 105 * |
106 * `new Path('a/b/c').join(new Path('d/../../e')` returns the Path | 106 * `new _Path('a/b/c').join(new _Path('d/../../e')` returns the Path |
107 * containing `'a/b/e'`. | 107 * containing `'a/b/e'`. |
108 * | 108 * |
109 * Note that the join operation does not drop the last segment of the | 109 * Note that the join operation does not drop the last segment of the |
110 * base path, the way URL joining does. To join basepath to further using | 110 * base path, the way URL joining does. To join basepath to further using |
111 * URL semantics, use | 111 * URL semantics, use |
112 * [:basepath.directoryPath.join(further):]. | 112 * [:basepath.directoryPath.join(further):]. |
113 * | 113 * |
114 * If you want to avoid joins that traverse | 114 * If you want to avoid joins that traverse |
115 * parent directories in the base, you can check whether | 115 * parent directories in the base, you can check whether |
116 * `further.canonicalize()` starts with '../' or equals '..'. | 116 * `further.canonicalize()` starts with '../' or equals '..'. |
117 */ | 117 */ |
118 Path join(Path further); | 118 _Path join(_Path further); |
119 | 119 |
120 | 120 |
121 /** | 121 /** |
122 * Returns a path [:relative:] such that | 122 * Returns a path [:relative:] such that |
123 * [:base.join(relative) == this.canonicalize():]. | 123 * [:base.join(relative) == this.canonicalize():]. |
124 * Throws an exception if such a path is impossible. | 124 * Throws an exception if such a path is impossible. |
125 * For example, if [base] is '../../a/b' and [this] is '.'. | 125 * For example, if [base] is '../../a/b' and [this] is '.'. |
126 * The computation is independent of the file system and current directory. | 126 * The computation is independent of the file system and current directory. |
127 * | 127 * |
128 * To compute a relative path using URL semantics, where the final | 128 * To compute a relative path using URL semantics, where the final |
129 * path component of the base is dropped unless it ends with a slash, | 129 * path component of the base is dropped unless it ends with a slash, |
130 * call [: a.relativeTo(b.directoryPath) :] instead of [: a.relativeTo(b) :]. | 130 * call [: a.relativeTo(b.directoryPath) :] instead of [: a.relativeTo(b) :]. |
131 */ | 131 */ |
132 Path relativeTo(Path base); | 132 _Path relativeTo(_Path base); |
133 | 133 |
134 /** | 134 /** |
135 * Converts a path to a string using the native filesystem's conventions. | 135 * Converts a path to a string using the native filesystem's conventions. |
136 * | 136 * |
137 * Always returns '.' if the path is empty. | 137 * Always returns '.' if the path is empty. |
138 * On Windows, converts '/'s to backwards slashes, and removes | 138 * On Windows, converts '/'s to backwards slashes, and removes |
139 * the leading '/' if the path starts with a drive specification. | 139 * the leading '/' if the path starts with a drive specification. |
140 * For most valid Windows paths, this should be the inverse of the | 140 * For most valid Windows paths, this should be the inverse of the |
141 * conversion that the constructor new Path() performs. If the path is | 141 * conversion that the constructor new _Path() performs. If the path is |
142 * a Windows share, restores the '\\' at the start of the path. | 142 * a Windows share, restores the '\\' at the start of the path. |
143 */ | 143 */ |
144 String toNativePath(); | 144 String toNativePath(); |
145 | 145 |
146 /** | 146 /** |
147 * Returns the path as a string. If this path is constructed using | 147 * Returns the path as a string. If this path is constructed using |
148 * new Path.raw(), or new Path() on a non-Windows system, the | 148 * new _Path.raw(), or new _Path() on a non-Windows system, the |
149 * returned value is the original string argument to the constructor. | 149 * returned value is the original string argument to the constructor. |
150 */ | 150 */ |
151 String toString(); | 151 String toString(); |
152 | 152 |
153 /** | 153 /** |
154 * Gets the segments of a Path. The segments are just the result of | 154 * Gets the segments of a Path. The segments are just the result of |
155 * splitting the path on any '/' characters, except that a '/' at the | 155 * splitting the path on any '/' characters, except that a '/' at the |
156 * beginning does not create an empty segment before it, and a '/' at | 156 * beginning does not create an empty segment before it, and a '/' at |
157 * the end does not create an empty segment after it. | 157 * the end does not create an empty segment after it. |
158 * | 158 * |
159 * new Path('/a/b/c/d').segments() == ['a', 'b', 'c', d']; | 159 * new _Path('/a/b/c/d').segments() == ['a', 'b', 'c', d']; |
160 * new Path(' foo bar //../') == [' foo bar ', '', '..']; | 160 * new _Path(' foo bar //../') == [' foo bar ', '', '..']; |
161 */ | 161 */ |
162 List<String> segments(); | 162 List<String> segments(); |
163 | 163 |
164 /** | 164 /** |
165 * Appends [finalSegment] to a path as a new segment. Adds a '/' | 165 * Appends [finalSegment] to a path as a new segment. Adds a '/' |
166 * between the path and [finalSegment] if the path does not already end in | 166 * between the path and [finalSegment] if the path does not already end in |
167 * a '/'. The path is not canonicalized, and [finalSegment] may | 167 * a '/'. The path is not canonicalized, and [finalSegment] may |
168 * contain '/'s. | 168 * contain '/'s. |
169 */ | 169 */ |
170 Path append(String finalSegment); | 170 _Path append(String finalSegment); |
171 | 171 |
172 /** | 172 /** |
173 * Drops the final '/' and whatever follows it from this Path, | 173 * Drops the final '/' and whatever follows it from this Path, |
174 * and returns the resulting Path object. If the only '/' in | 174 * and returns the resulting Path object. If the only '/' in |
175 * this Path is the first character, returns '/' instead of the empty string. | 175 * this Path is the first character, returns '/' instead of the empty string. |
176 * If there is no '/' in the Path, returns the empty string. | 176 * If there is no '/' in the Path, returns the empty string. |
177 * | 177 * |
178 * new Path('../images/dot.gif').directoryPath == '../images' | 178 * new _Path('../images/dot.gif').directoryPath == '../images' |
179 * new Path('/usr/geoffrey/www/').directoryPath == '/usr/geoffrey/www' | 179 * new _Path('/usr/geoffrey/www/').directoryPath == '/usr/geoffrey/www' |
180 * new Path('lost_file_old').directoryPath == '' | 180 * new _Path('lost_file_old').directoryPath == '' |
181 * new Path('/src').directoryPath == '/' | 181 * new _Path('/src').directoryPath == '/' |
182 * Note: new Path('/D:/src').directoryPath == '/D:' | 182 * Note: new _Path('/D:/src').directoryPath == '/D:' |
183 */ | 183 */ |
184 Path get directoryPath; | 184 _Path get directoryPath; |
185 | 185 |
186 /** | 186 /** |
187 * The part of the path after the last '/', or the entire path if | 187 * The part of the path after the last '/', or the entire path if |
188 * it contains no '/'. | 188 * it contains no '/'. |
189 * | 189 * |
190 * new Path('images/DSC_0027.jpg).filename == 'DSC_0027.jpg' | 190 * new _Path('images/DSC_0027.jpg).filename == 'DSC_0027.jpg' |
191 * new Path('users/fred/').filename == '' | 191 * new _Path('users/fred/').filename == '' |
192 */ | 192 */ |
193 String get filename; | 193 String get filename; |
194 | 194 |
195 /** | 195 /** |
196 * The part of [filename] before the last '.', or the entire filename if it | 196 * The part of [filename] before the last '.', or the entire filename if it |
197 * contains no '.'. If [filename] is '.' or '..' it is unchanged. | 197 * contains no '.'. If [filename] is '.' or '..' it is unchanged. |
198 * | 198 * |
199 * new Path('/c:/My Documents/Heidi.txt').filenameWithoutExtension | 199 * new _Path('/c:/My Documents/Heidi.txt').filenameWithoutExtension |
200 * would return 'Heidi'. | 200 * would return 'Heidi'. |
201 * new Path('not what I would call a path').filenameWithoutExtension | 201 * new _Path('not what I would call a path').filenameWithoutExtension |
202 * would return 'not what I would call a path'. | 202 * would return 'not what I would call a path'. |
203 */ | 203 */ |
204 String get filenameWithoutExtension; | 204 String get filenameWithoutExtension; |
205 | 205 |
206 /** | 206 /** |
207 * The part of [filename] after the last '.', or '' if [filename] | 207 * The part of [filename] after the last '.', or '' if [filename] |
208 * contains no '.'. If [filename] is '.' or '..', returns ''. | 208 * contains no '.'. If [filename] is '.' or '..', returns ''. |
209 * | 209 * |
210 * new Path('tiger.svg').extension == 'svg' | 210 * new _Path('tiger.svg').extension == 'svg' |
211 * new Path('/src/dart/dart_secrets').extension == '' | 211 * new _Path('/src/dart/dart_secrets').extension == '' |
212 */ | 212 */ |
213 String get extension; | 213 String get extension; |
214 } | 214 } |
OLD | NEW |