First draft.

This document describes an interface for reading and writing stream of raw bytes, and classes built on top of it to provide string based reading and writing.

This specification refers to the ByteString and ByteArray classes defined in the Binary/B proposal, but it should be easy to adapt it to any definition of binary buffers or arrays.

Specification

Platforms implementing this specification must provide a top level io module. The io module must export the classes and interfaces described below.

Raw I/O

Stream

The Stream class implements a I/O stream for reading and writing raw bytes.

Constructor

Whether the Stream class provides a public constructor, and what the arguments of the constructor are, is not part of this specification. The process of creating actual Stream objects is implementation specific.

Various built-in modules such as the file module will know how to build native Stream objects in a platform specific way. Application classes should be able to extend the Stream class through JavaScript prototype chaining. However, duck typing should also work for Stream objects, meaning that any object implementing the Stream interface should work for code expecting an io.Stream object.

Instance Properties

Note: the length and position properties are used to implement random access streams traditionally implemented using the tell()/seek()/truncate() protocol. The rationale for departing from that nomenclature is that this puts stream more in line with other core objects such as String and Array. Also, random access streams are not often used in day-to-day programming, so these properties may most commonly be used for the in-memory ByteBuffer and StringBuffer streams defined below, where they should fit in nicely.

length Number

The length of the stream, in bytes. This property is only defined for seekable streams, and is only writable for streams that are both seekable and writable. Decreasing the length property of a stream causes the stream to be truncated. Increasing the length of a stream causes the stream to be extended. The content of the extended section of the stream are not defined.

position Number

The position within the stream at which the next read or write operation occurs, in bytes. This property is only defined for seekable streams. Setting it to a new value moves the stream's positon to the given byte offset.

Instance Methods

read(n Number) ByteString

Read up to n bytes from the stream, or until the end of the stream has been reached. An empty ByteString is returned when the end of the stream has been reached.

readAll() ByteString

Read all the bytes from the stream until its end has been reached. An empty ByteString is returned when the end of the stream has been reached.

readInto(buffer ByteArray, [begin Number], [end Number]) Number

Read bytes from the stream into the ByteArray buffer. This method does not increase the length of the ByteArray buffer. Returns the number of bytes read, or -1 if the end of the stream has been reached. Note: Can we safely return 0 on EOF?

skip(n Number) Number

Try to skip over n bytes in the stream.

write(b Binary, [begin Number], [end Number]) Number

Write bytes from b to the stream. If begin and end are specified, only the range starting at begin and ending before end are written. Returns the number of bytes actually written.

readable() Boolean

Returns true if the stream supports reading, false otherwise.

writable() Boolean

Returns true if the stream supports writing, false otherwise.

seekable() Boolean

Returns true if the stream supports the length and position properties, false otherwise. Note: we're not impelementing seek(), so should we find another term for this, too? 'positionable' comes to mind, but feels slightly awkward.

closed() Boolean

Returns true if the stream is closed, false otherwise.

flush()

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

close()

Closes the stream, freeing the resources it is holding.

Text I/O

TextStream

The TextStream class wraps a raw stream and exposes a similar interface as the Stream class, but its write() method takes a string as first arguments and its read() method returns a string. Additionally, it defines the properties and methods listed below.

Constructor

[new] TextStream(raw Stream, [options Object]) TextStream

Build a TextStream around a raw byte stream. The options argument may contain the following properties:

• charset: a string containing the name of the encoding to use
• newline: a string containing the newline character sequence to use
• delimiter: a string containing the delimiter to use in print()

Instance Properties

raw

A readonly property containing the raw byte stream wrapped by this text stream.

Instance Methods

readLine() String

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

readLines() Array*String

Returns an Array of Strings accumulated by calling readLine until an empty string turns up. Does not include the final empty string, and does include newline at the end of every line.

next() String throws StopIteration

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

iterator() Iterator

Returns the reader itself.

writeLine(line String)

Writes line followed by a newline.

print(...)

writes a delimiter delimited array of Strings terminated with a newline.

Memory based I/O

The io module provides two classes for in-memory streams: ByteBuffer for a stream backed by a ByteArray, and StringBuffer for an memory-backed text stream that works with strings.

Memory streams are readable, writable, and seekable and implement the interface defined for Stream and TextStream, respectively, including the read(), readInto(), and write() methods and the length, and position properties.

ByteBuffer

The ByteBuffer class implements a raw byte based I/O stream as a memory buffer.

Constructor

[new] ByteBuffer() ByteBuffer

Create a new ByteBuffer with the default capacity

[new] ByteBuffer(b Binary) ByteBuffer

Create a new ByteBuffer with the bytes from b as initial content

[new] ByteBuffer(l Number) ByteBuffer

Create a new ByteBuffer with a capacity of l bytes

Instance Methods

In addition to the methods and properties defined for the Stream class, ByteBuffers implement the following methods:

append(b Binary, [begin Number], [end Number]) ByteBuffer

Append b or, if begin and end are specified, a subrange of b to the end of the buffer, increasing its length by the number of appended bytes. This is equal to setting the stream's position to the value of its length property and then calling write(b). This methods returns the buffer it was invoked on.

insert(pos Number, b Binary, [begin Number], [end Number]) ByteBuffer

Insert b or, if begin and end are specified, a subrange of b at the given position, moving any bytes above that position and increasing the buffer's length by the number of inserted bytes. This methods returns the buffer it was invoked on.

remove(begin Number, end Number) ByteBuffer

Remove a range of bytes from the buffer, moving any bytes above the range and decreasing the buffer's length by the number of removed bytes. This methods returns the buffer it was invoked on.

toByteString() ByteString

Return the content of the whole buffer as ByteString

StringBuffer

The StringBuffer class implements a string byte based I/O stream as a memory buffer.

Constructor

[new] StringBuffer() StringBuffer

Create a new StringBuffer with the default capacity

[new] StringBuffer(s String) StringBuffer

Create a new StringBuffer with the characters from s as inital content

[new] StringBuffer(l Number) StringBuffer

Create a new StringBuffer with a capacity of l bytes

Instance Methods

In addition to the methods and properties defined for the TextStream class, ByteBuffers implement the following methods:

append(s String, [begin Number], [end Number]) StringBuffer

Append s or, if begin and end are specified, a substring of s to the end of the buffer, increasing its length by the number of appended characters. This is equal to setting the stream's position to the value of its length property and then calling write(s). This methods returns the buffer it was invoked on.

insert(pos Number, s String, [begin Number], [end Number]) StringBuffer

Insert s or, if begin and end are specified, a substring of s at the given position, moving any characters above that position and increasing the buffer's length by the length of the inserted string. This methods returns the buffer it was invoked on.

remove(begin Number, end Number) StringBuffer

Remove a range of characters from the buffer, moving down any characters above the range and decreasing the buffer's length by the number of removed bytes. This methods returns the buffer it was invoked on.

toString() String

Return the value of the whole buffer as String

Errors

IOError

IOError is thrown by stream methods to signal an error in the underlying I/O medium.

Constructor

[new] IOError(message String) IOError

Create a new IOError with the given message.

Instance Properties

name String

The error name: "IOError"

message String

The error message

Instance Methods

toString() String

A description of the error in the format "name: message"

Notes

• This proposal does not describe non-blocking I/O, nor does it describe buffered I/O. These may be introduced in a later revision of the spec, possibly in conjunction with a Socket API. Platforms are free to implement non-blocking and buffered I/O in their own specific way.