File

A File object can be used to read and write to a location on disk. Files are generally created through the nova.fs.open() method of the FileSystem class.

File Modes and Encodings

Files can be created in one of two modes: “Binary Mode” or “Text Mode”. In Binary mode, reading from the file will read ArrayBuffer objects. In Text mode, the file object will attempt to interpret read data in a specific encoding (specified when the file was created) and return string objects. By default, the encoding of a file in text mode with no encoding specified is UTF-8.

Reading from a file in text mode is guaranteed to not return data broken up in the middle of multi-byte code points. If bytes are read that do not form complete code points in the relevant encoding, they will be stored in an internal buffer and interpreted during the next read operation.

See the documentation on the nova.fs.open() method of the FileSystem class for more information about opening files in specific modes.

Properties

closed

Whether the file has been closed. Once a file is closed, attempts to read, write, or seek within the file will throw an Error.

This property is readonly.

path

The path to the file on disk, as a string.

This property is readonly.

Methods

close()

Closes the file, releasing the underlying file descriptor. If the file is already closed, this method does nothing. Once a file is closed, attempts to read, write, or seek within the file will throw an Error.

tell()

Returns the current position within the file as a number.

seek(offset, [from])

This method moves the object’s position forward or backward by an amount specified by the offset argument. By default, this is relative to the file’s current position.

If the optional from argument is specified, the move can be relative to the start of the file (from == nova.fs.START), the current position (from == nova.fs.CURRENT), the end of the file (from == nova.fs.END).

read([size])

Reads a number of bytes from the file at the current offset. If the size argument is specified, the file will attempt to read up to that number of bytes. If no more bytes are available, null will be returned.

When bytes are successfully read, if the file is in Binary mode, the returned object will be a ArrayBuffer object. If it’s in Text mode, the returned object will be a string created using the file’s set encoding.

readline()

Reads a single line from the file, up to and including any newline. This can be used in a loop to read lines from a file efficiently. When reading the last line of a file, the returned string will not contain a newline. Thus, the return value should be unambiguous as to whether the end of the file has been reached.

This method is only valid for files in Text mode. Attempting to invoke this method on a file in Binary mode will throw an Error.

readlines()

Reads all remaining lines from the file in a loop using the readline() method, returning them as an array of strings.