File

Module	ejs.io
Namespace	"ejs.io"
Definition	class File
Specified	Ejs-12.
Inheritance	File 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

Qualifiers	Property	Type	Description
No properties defined

File Methods

Qualifiers	Method
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.

Inherited Methods

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.