MozillaWiki

ServerJS/IO/A: Difference between revisions

Page Discussion

ServerJS/IO/A (view source)

Revision as of 11:55, 8 September 2009

3,230 bytes added ,  8 September 2009
no edit summary
No edit summary
No edit summary
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
Work in progress.
''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 defines an interface for raw, byte based I/O, and classes for buffered and text based I/O layered upon the raw I/O.
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. null is returned when 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
:Skip over n bytes in the stream.
: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 the  
: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.


;isReadable() Boolean
;readable() Boolean
:Returns true if the stream supports reading, false otherwise.
:Returns true if the stream supports reading, false otherwise.


;isWritable() Boolean
;writable() Boolean
:Returns true if the stream supports writing, false otherwise.
:Returns true if the stream supports writing, false otherwise.


;isSeekable() 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.''


;isOpen() Boolean
;closed() Boolean
:Returns true if the stream is open.
:Returns true if the stream is closed, false otherwise.


;flush()
;flush()
Line 68: Line 68:
== Text I/O ==
== Text I/O ==


todo
=== 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 ==
== Memory based I/O ==
Line 95: 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 123: 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])
;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.
: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
:Return the value of the whole buffer as 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 =
= 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.
Hannesw
55

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/166943...167020"