Stream Object

A Stream object allows data to be read and written to files, memory buffers etc. There are various types of stream:

`empty`	a stream which is not yet open
`file`	access to data in a file
`string`	allows data to be read from a String
`octet`	allows data to be read/written to a buffer held in memory
`stdio`	allows data to be read/written to the standard output

Stream Creation

The create function can be used to create a Stream object eg.

    (create Stream)

Once created, this module is tailored using its properties and methods. The type of stream is defined by the way it is opened

Stream Properties

A Stream object supports the following properties:

property name	property type	description
`mode`	String	this determines whether data read from the stream is returned as String or Binary data -- legal values for the `mode` property are `string` or `binary`
`file`	String	the name of any file bound to the stream
`line`	Integer	the current line within the stream data
`positionInLine`	Integer	the position in the current line within the stream data

Stream Methods

The Stream object supports the following methods:

method name	description
`type`	returns which type of stream this is
`open`	open the stream in the supplied manner
`read`	read data from the stream
`write`	write data to the stream
`close`	close the stream
`finished`	determine if more data can be read from the stream
`print`	print data to the stream
`printAux`	print data to the stream, treating strings slightly differently
`readUntil`	read from the stream until a character is met within the supplied string
`readWhile`	read from the stream while the stream data is within the supplied string
`string`	retrieve the string data from the stream -- only valid if the stream type is `string` or `octet`
`binary`	retrieve the binary data from the stream -- only valid if the stream type is `string` or `octet`

`type`

Returns which type of stream this is ie.:

`empty`	a stream which is not yet open
`file`	access to data in a file
`string`	allows data to be read from a String
`octet`	allows data to be read/written to a buffer held in memory
`stdio`	allows data to be read/written to the standard output
`comms`	allows data to be read/written to a comms module

Arguments: none

Return type: String

`open`

Open the stream using the supplied manner. The arguments supplied to the initial call to open on a stream define the type of the stream as follows:

Arguments:

create a file stream:

filename String

mode String

The mode is often one of the following values:

rb read only for binary data

wb write only for binary data

rwb read/write only for binary data

ab append mode for binary data
create a string stream for reading data from a string:

data String
create an octet stream for writing then reading data into/from memory:
no arguments

Return type: the empty List ()

`read`

Read up to the supplied number of bytes from the stream. This is returned as a String or Binary depending on the value of the mode property.

Arguments:

nBytes Integer

Return type: String or Binary depending on the mode property.

`write`

Write data to the stream.

Arguments:

data	`String`, `Binary` or `Buffer`

Return type: the empty List ()

`close`

Close the stream.

Arguments: none

Return type: the empty List ()

`finished`

Determine if more data can be read from the stream.

Arguments: none

Return type: Object

`print`

Print data to the stream.

Arguments: any number of objects of any type

Return type: the empty List ()

`printAux`

Print data to the stream. If a String is supplied, it is printed to the stream without its enclosing quotes.

Arguments: any number of objects of any type

Return type: the empty List ()

`readUntil`

Read from the stream until a character is met within the supplied string.

Arguments:

data	`String`, `Binary` or `Integer`

Return type: the String of the collected data not including the terminating character in the supplied string

`readWhile`

Read from the stream while the stream data is within the supplied string.

Arguments:

data	`String`, `Binary` or `Integer`

Return type: the String of the collected data where all the characters are contiguous on the stream and are in the supplied string.

`string`

Retrieve the string data from the stream -- only valid if the stream type is string or octet.

Arguments: none

Return type: String

`binary`

Retrieve the binary data from the stream -- only valid if the stream type is string or octet.

Arguments: none

Return type: Binary

Contents

Current topic: objects

`rb`	read only for binary data
`wb`	write only for binary data
`rwb`	read/write only for binary data
`ab`	append mode for binary data