OLD | NEW |
1 // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2016, 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 library front_end.file_system; | 5 library front_end.file_system; |
6 | 6 |
7 import 'dart:async'; | 7 import 'dart:async'; |
8 | 8 |
9 import 'package:path/path.dart' as path; | 9 import 'package:path/path.dart' as path; |
10 | 10 |
11 /// Abstract interface to file system operations. | 11 /// Abstract interface to file system operations. |
12 /// | 12 /// |
13 /// All front end interaction with the file system goes through this interface; | 13 /// All front end interaction with the file system goes through this interface; |
14 /// this makes it possible for clients to use the front end in a way that | 14 /// this makes it possible for clients to use the front end in a way that |
15 /// doesn't require file system access (e.g. to run unit tests, or to run | 15 /// doesn't require file system access (e.g. to run unit tests, or to run |
16 /// inside a browser). | 16 /// inside a browser). |
17 /// | 17 /// |
18 /// Not intended to be implemented or extended by clients. | 18 /// Not intended to be implemented or extended by clients. |
19 abstract class FileSystem { | 19 abstract class FileSystem { |
20 /// Returns a path context suitable for use with this [FileSystem]. | 20 /// Returns a path context suitable for use with this [FileSystem]. |
21 path.Context get context; | 21 path.Context get context; |
22 | 22 |
23 /// Returns a [FileSystemEntity] corresponding to the given [path]. | |
24 /// | |
25 /// Uses of `..` and `.` in path are normalized before returning (so, for | |
26 /// example, `entityForPath('./foo')` and `entityForPath('foo')` are | |
27 /// equivalent). Relative paths are also converted to absolute paths. | |
28 /// | |
29 /// Does not check whether a file or folder exists at the given location. | |
30 FileSystemEntity entityForPath(String path); | |
31 | |
32 /// Returns a [FileSystemEntity] corresponding to the given [uri]. | 23 /// Returns a [FileSystemEntity] corresponding to the given [uri]. |
33 /// | 24 /// |
34 /// Uses of `..` and `.` in the URI are normalized before returning. | 25 /// Uses of `..` and `.` in the URI are normalized before returning. |
35 /// | 26 /// |
36 /// If [uri] is not an absolute `file:` URI, an [Error] will be thrown. | 27 /// If the URI scheme is not supported by this file system, an [Error] will be |
| 28 /// thrown. |
37 /// | 29 /// |
38 /// Does not check whether a file or folder exists at the given location. | 30 /// Does not check whether a file or folder exists at the given location. |
39 FileSystemEntity entityForUri(Uri uri); | 31 FileSystemEntity entityForUri(Uri uri); |
40 } | 32 } |
41 | 33 |
42 /// Abstract representation of a file system entity that may or may not exist. | 34 /// Abstract representation of a file system entity that may or may not exist. |
43 /// | 35 /// |
44 /// Instances of this class have suitable implementations of equality tests and | 36 /// Instances of this class have suitable implementations of equality tests and |
45 /// hashCode. | 37 /// hashCode. |
46 /// | 38 /// |
47 /// Not intended to be implemented or extended by clients. | 39 /// Not intended to be implemented or extended by clients. |
48 abstract class FileSystemEntity { | 40 abstract class FileSystemEntity { |
49 /// Returns the absolute normalized path represented by this file system | 41 /// Returns the absolute normalized URI represented by this file system |
50 /// entity. | 42 /// entity. |
51 /// | 43 /// |
52 /// Note: if the [FileSystemEntity] was created using | 44 /// Note: this is not necessarily the same as the URI that was passed to |
53 /// [FileSystem.entityForPath], this is not necessarily the same as the path | 45 /// [FileSystem.entityForUri], since the URI might have been normalized. |
54 /// that was used to create the object, since the path might have been | 46 Uri get uri; |
55 /// normalized. | |
56 String get path; | |
57 | 47 |
58 /// Attempts to access this file system entity as a file and read its contents | 48 /// Attempts to access this file system entity as a file and read its contents |
59 /// as raw bytes. | 49 /// as raw bytes. |
60 /// | 50 /// |
61 /// If an error occurs while attempting to read the file (e.g. because no such | 51 /// If an error occurs while attempting to read the file (e.g. because no such |
62 /// file exists, or the entity is a directory), the future is completed with | 52 /// file exists, or the entity is a directory), the future is completed with |
63 /// an [Exception]. | 53 /// an [Exception]. |
64 Future<List<int>> readAsBytes(); | 54 Future<List<int>> readAsBytes(); |
65 | 55 |
66 /// Attempts to access this file system entity as a file and read its contents | 56 /// Attempts to access this file system entity as a file and read its contents |
67 /// as a string. | 57 /// as a string. |
68 /// | 58 /// |
69 /// The file is assumed to be UTF-8 encoded. | 59 /// The file is assumed to be UTF-8 encoded. |
70 /// | 60 /// |
71 /// If an error occurs while attempting to read the file (e.g. because no such | 61 /// If an error occurs while attempting to read the file (e.g. because no such |
72 /// file exists, the entity is a directory, or the file is not valid UTF-8), | 62 /// file exists, the entity is a directory, or the file is not valid UTF-8), |
73 /// the future is completed with an [Exception]. | 63 /// the future is completed with an [Exception]. |
74 Future<String> readAsString(); | 64 Future<String> readAsString(); |
75 } | 65 } |
OLD | NEW |