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 buffered and 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 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 Methods

read(n Number) ByteString

readAll() ByteString

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

skip(n Number) Number

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

tell() Number

seek(position Number, whence Number)

truncate([length Number=0])

rewind()

readable() Boolean

writable() Boolean

seekable() Boolean

Memory based I/O

The io module provides two classes for in-memory stream: ByteBuffer for an in-memory stream backed by a ByteArray, and StringBuffer for an in-memory text stream that works with strings. Memory based streams implement the same interface as the Stream and TextStream classes, respectively, and are readable, writable, and seekable.

ByteBuffer

[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

toByteString

toByteArray

toBinary

StringBuffer

[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

toString()