File

Moduleejs.io
Namespace"ejs.io"
Definition class File
SpecifiedEjs-12.
InheritanceFile inherit Object

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. defined via the callback property.


Properties

QualifiersPropertyTypeDescription
No properties defined

File Methods

QualifiersMethod
public available(): Number
 Return the number of bytes available to read.
public get canRead(): Boolean
 Determine if the file can be read.
public get canWrite(): Boolean
 Determine if the file can be written.
public close(graceful: Boolean): Void
 Close the input stream and free up all associated resources.
File(path: Object, options: Object)
 Create a File object and open the requested path.
public flush(): 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 get isOpen(): Boolean
 Determine if the file is open.
public open(options: Object): File
public get options(): Object
 Get the file options.
public get path(): Path
 Get the name of the file associated with this File object.
public get position(): Number
 Get the current I/O position in the file.
public set position(value: Number): Void
 Seek to a new location in the file and set the File marker to a new read/write position.
public read(buffer: ByteArray, offset: Number, count: Number): Number
 Read a block of data from a file into a byte array.
public readBytes(count: Number): ByteArray
 Read data bytes from a file and return a byte array containing the data.
public readString(count: Number): String
 Read data from a file as a string.
public remove(): Void
 Remove a file.
public get size(): Number
 Get the size of the file.
public skip(n: Number): Void
public truncate(value: Number): Void
 Truncate the file.
public write(items: Array): Number
 Write data to the file.

Method Detail

public available(): Number

Return the number of bytes available to read.

Returns
A the number of available bytes.

get public canRead(): Boolean

Determine if the file can be read.

Returns
True if the file is open and can be read.

get public canWrite(): Boolean

Determine if the file can be written.

Returns
True if the file is open and can be written.

public close(graceful: Boolean): 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]

File(path: Object, options: Object)

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 open options are provided, the file is opened. See $open for the available options.

public flush(): Void

Flush any buffered data.

Description
This is a noop and is supplied just to comply with the Stream interface.

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.

get public isOpen(): Boolean

Determine if the file is open.

Returns
True if the file is open.

public open(options: Object): File

get public options(): Object

Get the file options.

Returns
The file options object hash.

get public path(): Path

Get the name of the file associated with this File object.

Returns
The name of the file or null if there is no associated file.

get public position(): Number

Get the current I/O position in the file.

Returns
The current read / write position in the file.

Throws

IOError: if the seek failed.


set public position(value: Number): Void

Seek to a new location in the file and set the File marker to a new read/write position.

Parameters

Throws

IOError: if the seek failed.


public read(buffer: ByteArray, offset: Number, count: Number): Number

Read a block of data from a file into a byte array.

Description
This will advance the read position.
Parameters
buffer: ByteArray Destination byte array for the read data.
offset: Number Offset in the byte array to place the data.
count: Number Number of bytes to read. If -1, read the entire file
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): 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.
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): String

Read data from a file as a string.

Parameters
count: Number Number of bytes to read. If -1, read the entire file.
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.


get public size(): Number

Get the size of the file.

Returns
The number of bytes in the file or -1 if size determination failed.

public skip(n: Number): Void

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.