File objects are references to files.

If path is a symbolic link, rather than a file, then the methods of File operate on the ultimate target of the link, except for File.delete and File.deleteSync, which operate on the link.

To operate on the underlying file data there are two options:

• Use streaming: read the contents of the file from the Stream this.openRead() and write to the file by writing to the IOSink this.openWrite().

• Open the file for random access operations using open.

abstract class File implements FileSystemEntity {
 /**
  * Create a File object.
  */
 factory File(String path) => new _File(path);

 /**
  * Create a File object from a Path object.
  */
 factory File.fromPath(Path path) => new _File.fromPath(path);

 /**
  * Create the file. Returns a [:Future<File>:] that completes with
  * the file when it has been created.
  *
  * Existing files are left untouched by [create]. Calling [create] on an
  * existing file might fail if there are restrictive permissions on
  * the file.
  */
 Future<File> create();

 /**
  * Synchronously create the file. Existing files are left untouched
  * by [createSync]. Calling [createSync] on an existing file might fail
  * if there are restrictive permissions on the file.
  *
  * Throws a [FileIOException] if the operation fails.
  */
 void createSync();

 /**
  * Delete the file. Returns a [:Future<File>:] that completes with
  * the file when it has been deleted. Only a file or a link to a file
  * can be deleted with this method, not a directory or a broken link.
  */
 Future<File> delete();

 /**
  * Synchronously delete the file. Only a file or a link to a file
  * can be deleted with this method, not a directory or a broken link.
  *
  * Throws a [FileIOException] if the operation fails.
  */
 void deleteSync();

 /**
  * Get a [Directory] object for the directory containing this
  * file.
  */
 Directory get directory;

 /**
  * Get the length of the file. Returns a [:Future<int>:] that
  * completes with the length in bytes.
  */
 Future<int> length();

 /**
  * Synchronously get the length of the file.
  *
  * Throws a [FileIOException] if the operation fails.
  */
 int lengthSync();

 /**
  * Get the last-modified time of the file. Returns a
  * [:Future<DateTime>:] that completes with a [DateTime] object for the
  * modification date.
  */
 Future<DateTime> lastModified();

 /**
  * Get the last-modified time of the file. Throws an exception
  * if the file does not exist.
  *
  * Throws a [FileIOException] if the operation fails.
  */
 DateTime lastModifiedSync();

 /**
  * Open the file for random access operations. Returns a
  * [:Future<RandomAccessFile>:] that completes with the opened
  * random access file. [RandomAccessFile]s must be closed using the
  * [RandomAccessFile.close] method.
  *
  * Files can be opened in three modes:
  *
  * [FileMode.READ]: open the file for reading.
  *
  * [FileMode.WRITE]: open the file for both reading and writing and
  * truncate the file to length zero. If the file does not exist the
  * file is created.
  *
  * [FileMode.APPEND]: same as [FileMode.WRITE] except that the file is
  * not truncated.
  */
 Future<RandomAccessFile> open({FileMode mode: FileMode.READ});

 /**
  * Synchronously open the file for random access operations. The
  * result is a [RandomAccessFile] on which random access operations
  * can be performed. Opened [RandomAccessFile]s must be closed using
  * the [RandomAccessFile.close] method.
  *
  * See [open] for information on the [mode] argument.
  *
  * Throws a [FileIOException] if the operation fails.
  */
 RandomAccessFile openSync({FileMode mode: FileMode.READ});

 /**
  * Get the canonical full path corresponding to the file path.
  * Returns a [:Future<String>:] that completes with the path.
  */
 Future<String> fullPath();

 /**
  * Synchronously get the canonical full path corresponding to the file path.
  *
  * Throws a [FileIOException] if the operation fails.
  */
 String fullPathSync();

 /**
  * Create a new independent [Stream] for the contents of this file.
  *
  * If [start] is present, the file will be read from byte-offset [start].
  * Otherwise from the beginning (index 0).
  *
  * If [end] is present, only up to byte-index [end] will be read. Otherwise,
  * until end of file.
  *
  * In order to make sure that system resources are freed, the stream
  * must be read to completion or the subscription on the stream must
  * be cancelled.
  */
 Stream<List<int>> openRead([int start, int end]);

 /**
  * Creates a new independent [IOSink] for the file. The
  * [IOSink] must be closed when no longer used, to free
  * system resources.
  *
  * An [IOSink] for a file can be opened in two modes:
  *
  * * [FileMode.WRITE]: truncates the file to length zero.
  * * [FileMode.APPEND]: sets the initial write position to the end
  *   of the file.
  *
  *  When writing strings through the returned [IOSink] the encoding
  *  specified using [encoding] will be used. The returned [IOSink]
  *  has an [:encoding:] property which can be changed after the
  *  [IOSink] has been created.
  */
 IOSink openWrite({FileMode mode: FileMode.WRITE,
                   Encoding encoding: Encoding.UTF_8});

 /**
  * Read the entire file contents as a list of bytes. Returns a
  * [:Future<List<int>>:] that completes with the list of bytes that
  * is the contents of the file.
  */
 Future<List<int>> readAsBytes();

 /**
  * Synchronously read the entire file contents as a list of bytes.
  *
  * Throws a [FileIOException] if the operation fails.
  */
 List<int> readAsBytesSync();

 /**
  * Read the entire file contents as a string using the given
  * [Encoding].
  *
  * Returns a [:Future<String>:] that completes with the string once
  * the file contents has been read.
  */
 Future<String> readAsString({Encoding encoding: Encoding.UTF_8});

 /**
  * Synchronously read the entire file contents as a string using the
  * given [Encoding].
  *
  * Throws a [FileIOException] if the operation fails.
  */
 String readAsStringSync({Encoding encoding: Encoding.UTF_8});

 /**
  * Read the entire file contents as lines of text using the given
  * [Encoding].
  *
  * Returns a [:Future<List<String>>:] that completes with the lines
  * once the file contents has been read.
  */
 Future<List<String>> readAsLines({Encoding encoding: Encoding.UTF_8});

 /**
  * Synchronously read the entire file contents as lines of text
  * using the given [Encoding].
  *
  * Throws a [FileIOException] if the operation fails.
  */
 List<String> readAsLinesSync({Encoding encoding: Encoding.UTF_8});

 /**
  * Write a list of bytes to a file.
  *
  * Opens the file, writes the list of bytes to it, and closes the file.
  * Returns a [:Future<File>:] that completes with this [File] object once
  * the entire operation has completed.
  *
  * By default [writeAsBytes] creates the file for writing and truncates the
  * file if it already exists. In order to append the bytes to an existing
  * file, pass [FileMode.APPEND] as the optional mode parameter.
  */
 Future<File> writeAsBytes(List<int> bytes, {FileMode mode: FileMode.WRITE});

 /**
  * Synchronously write a list of bytes to a file.
  *
  * Opens the file, writes the list of bytes to it and closes the file.
  *
  * By default [writeAsBytesSync] creates the file for writing and truncates
  * the file if it already exists. In order to append the bytes to an existing
  * file, pass [FileMode.APPEND] as the optional mode parameter.
  *
  * Throws a [FileIOException] if the operation fails.
  */
 void writeAsBytesSync(List<int> bytes, {FileMode mode: FileMode.WRITE});

 /**
  * Write a string to a file.
  *
  * Opens the file, writes the string in the given encoding, and closes the
  * file. Returns a [:Future<File>:] that completes with this [File] object
  * once the entire operation has completed.
  *
  * By default [writeAsString] creates the file for writing and truncates the
  * file if it already exists. In order to append the bytes to an existing
  * file, pass [FileMode.APPEND] as the optional mode parameter.
  */
 Future<File> writeAsString(String contents,
                            {FileMode mode: FileMode.WRITE,
                             Encoding encoding: Encoding.UTF_8});

 /**
  * Synchronously write a string to a file.
  *
  * Opens the file, writes the string in the given encoding, and closes the
  * file.
  *
  * By default [writeAsStringSync] creates the file for writing and
  * truncates the file if it already exists. In order to append the bytes
  * to an existing file, pass [FileMode.APPEND] as the optional mode
  * parameter.
  *
  * Throws a [FileIOException] if the operation fails.
  */
 void writeAsStringSync(String contents,
                        {FileMode mode: FileMode.WRITE,
                         Encoding encoding: Encoding.UTF_8});

 /**
  * Get the path of the file.
  */
 String get path;
}