File
| Module | ejs |
| Definition | final class File |
| Inheritance | File  Object |
| Specified | ejscript-2.7 |
| 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 |
|---|---|---|---|
| get | canRead | Boolean | Is the file opened for reading 0. |
| get | canWrite | Boolean | Is the file opened for writing 0. |
| get set | encoding | String | Current encoding schem for serializing strings. Defaults to "utf-8". |
| get | isOpen | Boolean | Is the file open. |
| get | options | Object | Current file options set when opening the file. |
| get | path | Path | The name of the file associated with this File object or null if there is no associated file. |
| get set | position | Number | The current read/write I/O position in the file. |
| get | size | Number | The size of the file in bytes. 0. |
File Class Methods
| Qualifiers | Method |
|---|
File Instance Methods
| Qualifiers | Method |
|---|---|
| File(path: Object, options: Object = null) | |
| Create a File object and open the requested path. | |
| close(): Void | |
| Close the input stream and free up all associated resources. | |
| 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)". | |
| open(options: Object = null): File | |
| Open a file. | |
| read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number | |
| Read a block of data from a file into a byte array. | |
| readBytes(count: Number = -1): ByteArray | |
| Read data bytes from a file and return a byte array containing the data. | |
| readString(count: Number = -1): String | |
| Read data from a file as a string. | |
| remove(): Boolean | |
| Remove a file. | |
| truncate(value: Number): Void | |
| Truncate the file. | |
| write(items: Array): Number | |
| Write data to the file. |
Method Detail
close(): Void
- Description
- Close the input stream and free up all associated resources.
override iterator get(): Iterator
- Description
- Iterate over the positions in a file. 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
- Description
- Get an iterator for this file to be used by "for each (v in obj)". Return each byte of the file in turn.
- Returns
- An iterator object that will return the bytes of the file.
- Description
- Open a file. 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, "c" to create the file if it does not exist, "l" to gain an exclusive lock, "s" for a shared lock, "t" for text mode, and "+" to never truncate. Defaults to "r". NOTE: not all platforms support "l" and "s". If "w" is specified and the file does not exist, it will be created. If "+" is not specified, the file will be truncated when opened, unless "a" is specified to append to existing content. If "c" is specified and the file exists, the open will fail. Use: "wa+" to append to a file and create if it does not exist. permissions Number containing the Posix permissions number value. Note: this is a number and not a string representation of an octal posix number. owner String representing the file owner (Not implemented). group String representing the file group (Not implemented).
- Returns
- The File object. This permits method chaining.
- Throws
- IOError: if the path or file cannot be created.
- Description
- Read a block of data from a file into a byte array. This will advance the read file's position. This will read up to count bytes that will fit into the provided buffer.
- 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 null on end of file.
- Throws
- IOError: if the file could not be read.
- Description
- Read data bytes from a file and return a byte array containing the data.
- Parameters
count: Number Number of bytes to read. If -1, 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.
remove(): Boolean
- Description
- Remove a file.
- Returns
- True if the file could be removed.
- Description
- Write data to the file. All I/O is unbuffered and synchronous.
- 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.