File
Module | ejs.io |
Definition | class File |
Inheritance | File ![]() |
Specified | ejscript-1.1 |
Stability | Evolving. |
The File class provides a foundation of I/O services to interact with physical files.
Each File object represents a single file, a named path to data stored in non-volatile memory. A File object provides methods for creating, opening, reading, writing and deleting a file, and for accessing and modifying information about the file. All I/O is unbuffered and synchronous.
Properties
Qualifiers | Property | Type | Description |
---|---|---|---|
public get | canRead | Boolean | Is the file opened for reading. |
public get | canWrite | Boolean | Is the file opened for writing. |
public get | isOpen | Boolean | Is the file open. |
public get | options | Object | Current file options set when opening the file. |
public get | path | Path | The name of the file associated with this File object or null if there is no associated file. |
public get set | position | Number | The current read/write I/O position in the file. |
public get | size | Number | The size of the file in bytes. |
File Methods
Qualifiers | Method |
---|---|
public | close(graceful: Boolean = true): Void |
Close the input stream and free up all associated resources. | |
File(path: Object, options: Object = null) | |
Create a File object and open the requested path. | |
public | flush(graceful: Boolean = true): Void |
Flush any buffered data. | |
iterator override | get(): Iterator |
Iterate over the positions in a file. | |
iterator override | getValues(): Iterator |
Get an iterator for this file to be used by "for each (v in obj)". | |
public | open(options: Object = null): File |
Open a file. | |
public | read(buffer: ByteArray, offset: Number = 0 , count: Number = -1): Number |
Read a block of data from a file into a byte array. | |
public | readBytes(count: Number = -1): ByteArray |
Read data bytes from a file and return a byte array containing the data. | |
public | readString(count: Number = -1): String |
Read data from a file as a string. | |
public | remove(): Void |
Remove a file. | |
public | truncate(value: Number): Void |
Truncate the file. | |
public | write(items: Array): Number |
Write data to the file. |
Method Detail
Close the input stream and free up all associated resources.
- Parameters
graceful: Boolean If true, then close the file gracefully after writing all pending data. [default: true]
Flush any buffered data.
- Description
- This is a noop and is supplied just to comply with the Stream interface.
- Parameters
graceful: Boolean If true, write all pending data. [default: true]
override iterator get(): Iterator
Iterate over the positions in a file.
- Description
- This will get an iterator for this file to be used by "for (v in files)".
- Returns
- An iterator object that will return numeric offset positions in the file.
override iterator getValues(): Iterator
Get an iterator for this file to be used by "for each (v in obj)".
- Description
- Return each byte of the file in turn.
- Returns
- An iterator object that will return the bytes of the file.
Open a file.
- Description
- This opens the file designated when the File constructor was called.
- Parameters
options: Object Optional options. If ommitted, the options default to open the file in read mode. Options can be either a mode string or can be an options hash. [default: null]
- Options
mode Optional file access mode string. Use "r" for read, "w" for write, "a" for append to existing content, "+" never truncate. Defaults to "r". permissions Number containing the Posix permissions value. Note: this is a number and not a string representation of an octal posix number.
- Returns
- The File object. This permits method chaining.
- Throws
- IOError: if the path or file cannot be created.
Read a block of data from a file into a byte array.
- Description
- This will advance the read file's position.
- Parameters
buffer: ByteArray Destination byte array for the read data. offset: Number Offset in the byte array to place the data. If the offset is -1, then data is appended to the buffer write position which is then updated. [default: 0 ] count: Number Number of bytes to read. If -1, read much as the buffer will hold up to the entire file if the buffer is of sufficient size or is growable. [default: -1]
- Returns
- A count of the bytes actually read. Returns 0 on end of file.
- Throws
- IOError: if the file could not be read.
Read data bytes from a file and return a byte array containing the data.
- Parameters
count: Number Number of bytes to read. If null, read the entire file. [default: -1]
- Returns
- A byte array containing the read data. Returns an empty array on end of file.
- Throws
- IOError: if the file could not be read.
Write data to the file.
- Description
- If the stream is in sync mode, the write call blocks until the underlying stream or endpoint absorbes all the data. If in async-mode, the call accepts whatever data can be accepted immediately and returns a count of the elements that have been written.
- Parameters
items: Array The data argument can be ByteArrays, strings or Numbers. All other types will call serialize first before writing. Note that numbers will not be written in a cross platform manner. If that is required, use the BinaryStream class to control the byte ordering when writing numbers.
- Returns
- The number of bytes written.
- Throws
- IOError: if the file could not be written.