| 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 |