ServerJS/IO/A: Difference between revisions

Jump to navigation Jump to search

ServerJS/IO/A (view source)

Revision as of 20:38, 7 September 2009

2,431 bytes added ,  7 September 2009
no edit summary
No edit summary
Line 1: Line 1:
Work in progress.
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 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 [[ServerJS/Binary/B|Binary/B]] proposal, but it should be easy to adapt it to any definition of binary buffers or arrays.
This specification refers to the ByteString and ByteArray classes defined in the [[ServerJS/Binary/B|Binary/B]] proposal, but it should be easy to adapt it to any definition of binary buffers or arrays.


== 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 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 ===
== Raw I/O ==


==== Stream ====
=== Stream ===


The Stream class implements a stream for reading and writing raw bytes.
The Stream class implements a stream for reading and writing raw bytes.
Line 19: Line 19:


:Various built-in modules such as the [[ServerJS/Filesystem_API|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.
:Various built-in modules such as the [[ServerJS/Filesystem_API|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 =====
===== Instance Methods =====


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


;readAll() ByteString
;readAll() ByteString
:  
:Read all the bytes from the stream until its end 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.


;skip(n Number) Number
;skip(n Number) Number
:  
: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
 
;tell() Number
:
 
;seek(position Number, whence Number)
:


;truncate([length Number=0])
;isReadable() Boolean
:
:Returns true if the stream supports reading, false otherwise.


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


;readable() Boolean
;isSeekable() Boolean
:
:Returns true if the stream supports the length and position properties, false otherwise


;writable() Boolean
;isOpen() Boolean
:
:Returns true if the stream is open.


;seekable() Boolean
;flush()
:
:Flushes the bytes written to the stream to the underlying medium.


=== Buffered I/O ===
;close()
:Closes the stream, freeing the resources it is holding.


=== Text I/O ===
== Text I/O ==


=== Memory based 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 implement the same interface as the Stream and TextStream classes, respectively, and are readable, writable, and seekable.
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 ====
=== ByteBuffer ===


;[new] ByteBuffer() ByteBuffer
;[new] ByteBuffer() ByteBuffer
Line 78: Line 83:


===== Instance Methods =====
===== Instance 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
;toByteString() ByteString
:Return the content of the whole buffer as ByteString
:Return the content of the whole buffer as ByteString


==== StringBuffer ====
=== StringBuffer ===


;[new] StringBuffer() StringBuffer
;[new] StringBuffer() StringBuffer
Line 94: Line 105:


===== Instance Methods =====
===== Instance 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
;toString() String
:Return the value of the whole buffer as String
:Return the value of the whole buffer as String
Hannesw
55

edits

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

Navigation menu