55
edits
ServerJS/IO/A: Difference between revisions
no edit summary
No edit summary |
|||
| (8 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
''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 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. | ||
| Line 7: | Line 7: | ||
= Specification = | = Specification = | ||
Platforms implementing this specification must provide a top level io module. The io module | 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 == | == Raw I/O == | ||
| Line 34: | Line 34: | ||
;read(n Number) ByteString | ;read(n Number) ByteString | ||
:Read up to n bytes from the stream, or until the end of the stream has been reached. | :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 | ;readAll() ByteString | ||
:Read all the bytes from the stream until its end has been reached. | :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 | ;readInto(buffer ByteArray, [begin Number], [end Number]) Number | ||
:Read bytes from the stream into the ByteArray buffer. | :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 | ;skip(n Number) Number | ||
: | :Try to skip over n bytes in the stream. | ||
;write(b Binary, [begin Number], [end Number]) Number | ;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. | :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 | ;readable() Boolean | ||
| Line 55: | Line 55: | ||
;seekable() Boolean | ;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?'' | :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 | ;closed() Boolean | ||
| Line 130: | Line 130: | ||
In addition to the methods and properties defined for the '''Stream''' class, ByteBuffers implement the following 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 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). | :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]) | ;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. | :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 | ;toByteString() ByteString | ||
| Line 158: | Line 161: | ||
In addition to the methods and properties defined for the '''TextStream''' class, ByteBuffers implement the following 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 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). | :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 | ;toString() String | ||
| Line 171: | Line 177: | ||
=== IOError === | === 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 = | = 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. | * 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. | ||