Module io

This module implements the Stream/TextStream classes as per the CommonJS IO/A proposal.

Class MemoryStream

Instance Methods

Instance Properties

Class Stream

Instance Methods

Instance Properties

Class TextStream

Instance Methods

Instance Properties


MemoryStream (binaryOrNumber)

A binary stream that reads from and/or writes to an in-memory byte array.

If the constructor is called with a Number argument, a ByteArray with the given length is allocated and the length of the stream is set to zero.

If the argument is a binary object it will be used as underlying buffer and the stream length set to the length of the binary object. If argument is a ByteArray, the resulting stream is both readable, writable, and seekable. If it is a ByteString, the resulting stream is readable and seekable but not writable.

If called without argument, a ByteArray of length 1024 is allocated as buffer.

Parameters

Binary|Number binaryOrNumber the buffer to use, or the initial capacity of the buffer to allocate.

MemoryStream.prototype.close ()

Closes the stream, freeing the resources it is holding.


MemoryStream.prototype.closed ()

Returns true if the stream is closed, false otherwise.

Returns

Boolean true if the stream has been closed

MemoryStream.prototype.content

The wrapped buffer.


MemoryStream.prototype.flush ()

Flushes the bytes written to the stream to the underlying medium.


MemoryStream.prototype.length

The number of bytes in the stream's underlying buffer.


MemoryStream.prototype.position

The current position of this stream in the wrapped buffer.


MemoryStream.prototype.read (maxBytes)

Read up to maxBytes bytes from the stream, or until the end of the stream has been reached. If maxBytes is not specified, the full stream is read until its end is reached. Reading from a stream where the end has already been reached returns an empty ByteString.

Parameters

Number maxBytes the maximum number of bytes to read

Returns

ByteString

See


MemoryStream.prototype.readInto (buffer, begin, end)

Read bytes from this stream into the given buffer. This method does not increase the length of the buffer.

Parameters

ByteArray buffer the buffer
Number begin optional begin index, defaults to 0.
Number end optional end index, defaults to buffer.length - 1.

Returns

Number The number of bytes read or -1 if the end of the stream has been reached

See


MemoryStream.prototype.readable ()

Returns true if the stream supports reading, false otherwise. Always returns true for MemoryStreams.

Returns

Boolean true if stream is readable

See


MemoryStream.prototype.seekable ()

Returns true if the stream is randomly accessible and supports the length and position properties, false otherwise. Always returns true for MemoryStreams.

Returns

Boolean true if stream is seekable

See


MemoryStream.prototype.writable ()

Returns true if the stream supports writing, false otherwise. For MemoryStreams this returns true if the wrapped binary is an instance of ByteArray.

Returns

Boolean true if stream is writable

See


MemoryStream.prototype.write (source, begin, end)

Write bytes from b to this stream. If begin and end are specified, only the range starting at begin and ending before end is written.

Parameters

Binary source The source to be written from
Number begin optional
Number end optional

See


Stream ()

This class implements an I/O stream used to read and write raw bytes.


Stream.prototype.close ()

Closes the stream, freeing the resources it is holding.


Stream.prototype.closed ()

Returns true if the stream has been closed, false otherwise.

Returns

Boolean true if the stream has been closed

Stream.prototype.copy (output)

Reads all data available from this stream and writes the result to the given output stream, flushing afterwards. Note that this function does not close this stream or the output stream after copying.

Parameters

Stream output The target Stream to be written to.

Stream.prototype.flush ()

Flushes the bytes written to the stream to the underlying medium.


Stream.prototype.forEach (fn, [thisObj])

Read all data from this stream and invoke function fn for each chunk of data read. The callback function is called with a ByteArray as single argument. Note that the stream is not closed after reading.

Parameters

Function fn the callback function
Object [thisObj] optional this-object to use for callback

Stream.prototype.inputStream

The wrapped java.io.InputStream.


Stream.prototype.outputStream

The wrapped java.io.OutputStream.


Stream.prototype.read (maxBytes)

Read up to maxBytes bytes from the stream, or until the end of the stream has been reached. If maxBytes is not specified, the full stream is read until its end is reached. Reading from a stream where the end has already been reached returns an empty ByteString.

Parameters

Number maxBytes the maximum number of bytes to read

Returns

ByteString

Stream.prototype.readInto (buffer, begin, end)

Read bytes from this stream into the given buffer. This method does not increase the length of the buffer.

Parameters

ByteArray buffer the buffer
Number begin optional begin index, defaults to 0.
Number end optional end index, defaults to buffer.length - 1.

Returns

Number The number of bytes read or -1 if the end of the stream has been reached

Stream.prototype.readable ()

Returns true if the stream supports reading, false otherwise.

Returns

Boolean true if stream is readable

Stream.prototype.seekable ()

Returns true if the stream is randomly accessible and supports the length and position properties, false otherwise.

Returns

Boolean true if stream is seekable

Stream.prototype.skip (num)

Try to skip over num bytes in the stream. Returns the number of acutal bytes skipped or throws an error if the operation could not be completed.

Parameters

Number num bytes to skip

Returns

Number actual bytes skipped

Stream.prototype.unwrap ()

Get the Java input or output stream instance wrapped by this Stream.


Stream.prototype.writable ()

Returns true if the stream supports writing, false otherwise.

Returns

Boolean true if stream is writable

Stream.prototype.write (source, begin, end)

Write bytes from b to this stream. If begin and end are specified, only the range starting at begin and ending before end is written.

Parameters

Binary source The source to be written from
Number begin optional
Number end optional

TextStream (io, options, buflen)

A TextStream implements an I/O stream used to read and write strings. It wraps a raw Stream and exposes a similar interface.

Parameters

Stream io The raw Stream to be wrapped.
Object options the options object. Supports the following properties:
  • charset: string containing the name of the encoding to use. Defaults to "utf8".
  • newline: string containing the newline character sequence to use. Defaults to "\n".
  • delimiter: string containing the delimiter to use in print(). Defaults to " ".
number buflen optional buffer size. Defaults to 8192.

TextStream.prototype.close ()

See


TextStream.prototype.content

If the wrapped stream is a MemoryStream this contains its content decoded to a String with this streams encoding. Otherwise contains an empty String.


TextStream.prototype.copy (output)

Reads from this stream with readLine, writing the results to the target stream and flushing, until the end of this stream is reached.

Parameters

output

TextStream.prototype.flush ()

See


TextStream.prototype.forEach (callback, [thisObj])

Calls callback with each line in the input stream.

Parameters

Function callback the callback function
Object [thisObj] optional this-object to use for callback

TextStream.prototype.iterator ()

Returns this stream.

Returns

TextStream this stream

TextStream.prototype.next ()

Returns the next line of input without the newline. Throws StopIteration if the end of the stream is reached.

Returns

String the next line

TextStream.prototype.print ()

Writes all argument values as a single line, delimiting the values using a single blank.


TextStream.prototype.raw

The wrapped binary stream.


TextStream.prototype.read ()

Read the full stream until the end is reached and return the data read as string.

Returns

String

TextStream.prototype.readInto (buffer)

Not implemented for TextStraim. Calling this method will raise an error.

Parameters

buffer

TextStream.prototype.readLine ()

Reads a line from this stream. If the end of the stream is reached before any data is gathered, returns an empty string. Otherwise, returns the line including the newline.

Returns

String the next line

TextStream.prototype.readLines ()

Returns an Array of Strings, accumulated by calling readLine until it returns an empty string. The returned array does not include the final empty string, but it does include a trailing newline at the end of every line.

Returns

Array an array of lines

TextStream.prototype.readable ()

See


TextStream.prototype.seekable ()

Always returns false, as a TextStream is not randomly accessible.


TextStream.prototype.writable ()

See


TextStream.prototype.write ()

Writes all arguments to the stream.


TextStream.prototype.writeLine (line)

Writes the given line to the stream, followed by a newline.

Parameters

line

TextStream.prototype.writeLines (lines)

Writes the given lines to the stream, terminating each line with a newline.

This is a non-standard extension, not part of CommonJS IO/A.

Parameters

lines