View source for IO/B/Stream/Level1

This proposal defines the '''''Stream''''' class portion of [[IO/B]].

Please also see [[Binary/C]] and [[IO/B/Stream/Level0]].

== Preamble ==
This proposal defines a Stream class which is completely generic. New types of
streams can be made JavaScript side either by using the raw IO interface defined
by IO/B/Raw, or by subclassing stream and borrowing methods directly defined
on another stream. (The former permits streams built on other data sources which
only require a simple raw api, and the latter permits Stream subclasses which
simply munge data or arguments for certain methods or add new ones)

The Stream class is intended to be extremely abstract makes no assumption to the
capabilities of the underlying source of the data; Almost every operation works
the same whether the stream is binary or text. Capabilities are duck-typed onto
the Stream instead of defining separate types of streams. Access to a binary
layer below a text layer is not assumed as streams may be implemented for any
data source, and some of those data sources (Like a Stream that works on a StringBuffer)
will already be text and thus will not support dual-layer text wrapped streaming.

== Terminology ==
;contentConstructor: ''See [[Binary/C]].''
;sequence: ''See [[Binary/C]].''
;''#'' units: A length measured in the relevant unit (Byte or Characters) for the given sequence type of the stream.

== Class api ==

;new Stream(Object def);
:''(Only required by the base Stream class)''
:Creates a new generic stream instance using <code>def</code> as a object defining what the stream can do and how to do it using the [[../Raw|Raw io api]].

;s.contentConstructor -> Function;
:contentConstructor MUST return either <code>Blob</code> or <code>String</code> to indicate the underlying type of the stream content.

;s.canRead -> boolean;
;s.canWrite -> boolean;
:''(canRead MAY not be present if the stream is not readable)''
:''(canWrite MAY not be present if the stream is not writeable)''
:Boolean getters indicating the readable state of the stream.
:* canRead/canWrite should be false if read/write is not able to read/write data right away.
:* canRead/canWrite should be true if read/write will return with data right away.
:* canRead MUST NOT be false if EOF has been reached and read will return an EOF indication right away.
:* canRead/canWrite MUST assume things are not blocked and return true if the underlying io api does not provide a mechanism to get this information.

;s.seenEOF -> boolean;
:Boolean property indicating if EOF has been reached.
:* .seenEOF must NOT be true before .read has returned an EOF indicator.

;s.position -> uint;
:The current position within the stream.
:* If <code>position</code> is so large that the number cannot be accurately represented (<code>p == p+1</code> is true) then <code>position</code> MUST return <code>Infinity</code>.
:* <code>position</code> is measured in the same units as the type of sequence specified by .contentConstructor;
:* <code>position</code> MUST work even when Stream is constructed without a position: key.
:** This may be implemented by incrementing an internal position counter with lengths as .reads, .writes, .skips, etc... are performed, and modifying it along with a .seek where .tell should also include information that can reconstruct .the .position inside of an opaque cookie.

;s.read() -> ''Sequence'';
;s.read(uint max) -> ''Sequence'';
:''(MUST not be present if the stream is not readable)''
:Reads data from the stream.
:* .read MUST ONLY return sequences of the same type as .contentConstructor;
:* If ''max'' is 0, negative or not a integer a TypeError SHOULD be thrown.
:** 0 MAY be given a different error message as rather than being an invalid number the issue is you cannot read nothing.
:* ''max'' is measured in the same units as the type of sequence specified by .contentConstructor;
:* If ''max'' is omitted then .read buffers the entire stream then returns it's contents.
:* If ''max'' is specified then .read will do a partial read.
:** The resulting data MAY be of length ''max'' OR less than ''max'' but MUST have a length greater than 0.
:* If EOF has been reached then .read should return an empty sequence of length 0.
:* If max is <code>null</code> it should be set to 1 (?narwhal)

;s.skip(uint max) -> uint;
:<del>''(MUST not be present if the stream is not readable)''</del>
:Skips over data as if reading from the stream.
:* If ''max'' is 0, negative or not a integer a TypeError SHOULD be thrown.
:** 0 MAY be given a different error message as rather than being an invalid number the issue is you cannot skip nothing.
:* ''max'' is measured in the same units as the type of sequence specified by .contentConstructor;
:* .skip does partial skips behaving similarly to .read;
:* .skip returns the number of units skipped in the skip. This number must be greater than 0.
:* If EOF has been reached then .skip should return 0.
:* .skip MUST be implemented on a readable stream even if not available in the underlying layer (it should use .read and discard the data if it needs to).

;s.write(''Sequence''|Buffer|''OpaqueRange'' data) -> ???;
:''(MUST not be present if the stream is not writable)''
:Writes data to the stream.
:* .write must fully write the data, it may not do partial writes.
:* .write SHOULD attempt try to memcopy data.

;s.writePartial(''Sequence''|Buffer|''OpaqueRange'' data, [offset=0]) -> uint;
:Writes data to the stream without blocking to wait for all the chunks to go through.
:* .write MUST write at least 1 unit of data or block till it is permitted to write.
:* .write returns the length of the data it wrote into the stream. The return value may be combined together and used as the offset to further calls.

;s.tell() -> ''OpaqueCookie''|uint;
:Returns the location within the stream in a format that can be used later by .seek
:* If this returns a Number it MUST be an integer indicating the location within the stream measured in the same units as the type of sequence specified by .contentConstructor;
:** Therefore, if this returns a number it should be the same as <code>position</code>.
:* An OpaqueCookie MUST contain enough information for .seek to later return to this location within the data and set .position back to the current state.
:* An OpaqueCookie returned by this function is only valid for this stream.
:* An OpaqueCookie returned by this function is invalid if a write has been made to a position in the stream before the location specified by this OpaqueCookie.

;s.seek(''OpaqueCookie''|uint to);
:''(MUST not be present if the stream is not seekable)''
:Seeks to another location within the file.
:* This method MUST accept any valid value outputted by .tell on the same stream.
:* If an OpaqueCookie is used as input and a write was made to a location before the location specified by that OpaqueCookie in between the time .tell was called and .seek is called behaviour is not defined and will likely break.

;s.rewind();
:''(MUST not be present if the stream is not seekable)''
:Seeks to the very beginning of the stream.

;s.flush();
:Flushes data which may be buffered in this or an underlying stream
:* If the underlying stream does not have a way to flush then this will be a no-op function.

;s.close();
:Closes the stream preventing any further reads or writes.
:* This must remove any .read, .write, or .seek present on the stream object.

== Requirements ==
Stream's constructor MUST be implemented such that <code>Stream.call(this, def);</code>
within a function that has a .prototype that inherits from Stream.prototype will
modify the object specified by <code>this</code> instead of constructing a new object.

This requirement is defined so that subclasses of Stream may be made using the
simple stub:
<source>
function StreamSubclass(o) {
	Stream.call(this, o);
}
StreamSubclass.prototype = new Stream();
</source>

== Notes and comment bait ==
* Should we specify that the OpaqueCookie returned by .tell should respond to > and < calls (this can fairly easily be made to work using .valueOf)