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 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 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
- isReadable() Boolean
- Returns true if the stream supports reading, false otherwise.
- isWritable() Boolean
- Returns true if the stream supports writing, false otherwise.
- isSeekable() Boolean
- Returns true if the stream supports the length and position properties, false otherwise
- isOpen() Boolean
- Returns true if the stream is open.
- 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
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 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
- [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)
- Append a binary to the end of the buffer. This is equal to setting the stream's position to the value of its length property followed by write(s).
- insert(b Binary, pos Number)
- Insert a binary at the given position, moving any characters above that position and increasing the length of the buffer by s.length.
- toByteString() ByteString
- Return the content of the whole buffer as ByteString
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
In addition to the methods and properties defined for the TextStream class, ByteBuffers implement the following methods:
- append(s String)
- Append a string to the end of the buffer. This is equal to setting the stream's position to the value of its length property followed by write(s).
- insert(s String, pos Number)
- Insert a string at the given position, moving any characters above that position and increasing the length of the buffer by s.length.
- toString() String
- Return the value of the whole buffer as String