File

Moduleejs.io
Definition class File
InheritanceFile inherit Object
Specifiedejscript-1.1
StabilityEvolving.

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

QualifiersPropertyTypeDescription
public get canReadBooleanIs the file opened for reading.
public get canWriteBooleanIs the file opened for writing.
public get isOpenBooleanIs the file open.
public get optionsObjectCurrent file options set when opening the file.
public get pathPathThe name of the file associated with this File object or null if there is no associated file.
public get setpositionNumberThe current read/write I/O position in the file.
public get sizeNumberThe size of the file in bytes.

File Methods

QualifiersMethod
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

public close(graceful: Boolean = true): Void

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]

public File(path: Object, options: Object = null)

Create a File object and open the requested path.

Parameters
path: Object The name of the file to associate with this file object. Can be either a String or a Path.
options: Object If the options are provided, the file is opened. See open for the available options. [default: null]

public flush(graceful: Boolean = true): Void

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.

public open(options: Object = null): 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
modeOptional file access mode string. Use "r" for read, "w" for write, "a" for append to existing content, "+" never truncate. Defaults to "r".
permissionsNumber 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.

public read(buffer: ByteArray, offset: Number = 0 , count: Number = -1): Number

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.

public readBytes(count: Number = -1): ByteArray

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.

public readString(count: Number = -1): String

Read data from a file as a string.

Parameters
count: Number Number of bytes to read. If -1, read the entire file. [default: -1]
Returns
A string containing the read data. Returns an empty string on end of file.
Throws
IOError: if the file could not be read.

public remove(): Void

Remove a file.

Throws
IOError: if the file could not be removed.

public truncate(value: Number): Void

Truncate the file.

Parameters
value: Number The new length of the file.
Throws
IOError: if the file's size cannot be changed

public write(items: Array): Number

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.