ServerJS/IO/A

Work in progress.

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 defines an interface for raw, byte based I/O, and classes for buffered and text based I/O layered upon the raw I/O.

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. null 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.

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

Read bytes from the stream into the ByteArray buffer.

skip(n Number) Number

Skip over n bytes in the stream.

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

Write bytes from the

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?

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

todo

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])

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).

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

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.

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])

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).

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

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.

toString() String

Return the value of the whole buffer as String

Errors

todo

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.