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