TextStream

Module	ejs
Definition	class TextStream
Inheritance	TextStream Object
Specified	ejscript-2.5
Stability	Evolving.

TextStreams interpret data as a stream of characters.

They provide methods to read and write data in various text encodings and to read/write lines of text appending appropriate system dependent new line terminators. TextStreams can be stacked upon other Streams such as files, byte arrays, sockets, or Http objects.

Properties

Qualifiers	Property	Type	Description
get set	async	Boolean	The current async mode. Set to true if the stream is in async mode.
get	length	Number	The number of bytes available to read without blocking. This is the number of bytes buffered internally by this stream. It does not include any data buffered downstream.

Inherited Properties

TextStream Class Methods

(No own class methods defined)

Qualifiers	Method

Inherited Methods

TextStream Instance Methods

Qualifiers	Method
	TextStream(stream: Stream)
	Create a text filter stream.
	close(): Void
	Close the stream.
	fill(): Number
	Fill the input buffer from upstream.
	flush(dir: Number): Void
	Flush the stream and underlying streams.
	off(name, observer: Function): Void
	Remove an observer from the stream.
	on(name, observer: Function): TextStream
	Add an observer to the stream for the named events.
	read(buffer: ByteArray, offset: Number = 0, count: Number = -1): Number
	Read characters from the stream into the supplied byte array.
	readLine(): String
	Read a line from the stream.
	readLines(numLines: Number = -1): Array
	Read a required number of lines of data from the stream.
	readString(count: Number = -1): String
	Read a string from the stream.
	write(data: Array): Number
	Write characters to the stream.
	writeLine(lines: Array): Number
	Write text lines to the stream.

Inherited Methods

Method Detail

TextStream(stream: Stream)

Description: Create a text filter stream. A Text filter stream must be stacked upon a stream source such as a File.

Parameters

stream: Stream

Stream data source/sink to stack upon.

close(): Void

Description: Close the stream.

Events

A close event is issued before closing the stream.

fill(): Number

Description: Fill the input buffer from upstream.

Returns: The number of new characters added to the input bufer.

flush(dir: Number): Void

Description: Flush the stream and underlying streams. A supplied flush direction argument modifies the effect of this call. If direction is set to Stream.READ, then all read data is discarded. If direction is set to Stream.WRITE, any buffered data is written. Stream.BOTH will cause both directions to be flushed. If the stream is in sync mode, this call will block until all data is written. If the stream is in async mode, it will attempt to write all data but will return immediately. Defaults to Stream.WRITE.

Parameters

dir: Number

Direction to flush. Set to READ WRITE or BOTH.

off(name, observer: Function): Void

Description: Remove an observer from the stream.

Parameters

name	Event name previously used with observe. The name may be an array of events.
observer: Function	Observer function previously used with observe.

on(name, observer: Function): TextStream

Description: Add an observer to the stream for the named events.

Parameters

name: [String\|Array]	Name of the event to listen for. The name may be an array of events.
observer: Function	Callback observer function. The function is called with the following signature: function observer(event: String, ...args): Void.

Events

readable	Issued when the stream becomes readable.
writable	Issued when the stream becomes writable.
close	Issued when stream is being closed. 8.

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

Description: Read characters from the stream into the supplied byte array.

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 characters to read. [default: -1]

Returns: A count of characters actually read.

Throws: IOError: if an I/O error occurs. `

readLine(): String

Description: Read a line from the stream.

Returns: A string containing the next line without newline characters ("\r", "\n"). Return null on EOF.

Throws: IOError: if an I/O error occurs.

readLines(numLines: Number = -1): Array

Description: Read a required number of lines of data from the stream.

Parameters

numLines: Number

Of lines to read. Defaults to read all lines. [default: -1]

Returns: Array containing the read lines. Lines are stripped of newline characters ("\r", "\n"). Return null on EOF.

Throws: IOError: if an I/O error occurs.

readString(count: Number = -1): String

Description: Read a string from the stream.

Parameters

count: Number

Of bytes to read. Returns the entire stream contents if count is -1. [default: -1]

Returns: A string or null on EOF.

Throws: IOError: if an I/O error occurs.

write(data: Array): Number

Description: Write characters to the stream.

Parameters

data: Array

String to write.

Returns: The total number of bytes that were written.

writeLine(lines: Array): Number

Description: Write text lines to the stream. The text line is written after appending the system text newline character(s).

Parameters

lines: Array

Text lines to write.

Returns: The number of characters written or -1 if unsuccessful.