BlueScript: Stream Objects

Contents

Description

Objects representing sequences of bytes (e.g. files) supporting a simple I/O model.

Documentation

Streams (sequences of bytes that can be read and-or written) are not returned by any function in Standard BlueScript. [Note: There are optional functions that do so - see below.] However, other modules may make use of stream objects, so the common methods for stream objects are denoted below.

Objects

stream

stream close
Usage
stream close
Explicitly closes the stream. Nothing further may be written to or read from the stream. Any buffers are flushed and the underlying stream implementation is notified of the closing. For example, if stream represents a network socket, the network socket will be shutdown.
stream flush
Usage
stream flush
Forces the stream to flush any output buffers, whether in the stream object itself or its underlying implementation.
stream getc
Usage
stream getc
Returns
The next character or an empty string if no characters are left.
Reads the next character from the stream and returns it. If there are no characters left in the stream, then an empty string is returned.
stream poll
Usage
stream poll (read|write)
Returns
True (1) if the corresponding operation would not block or false (0) if the operation would block.
Checks the given stream to see if there is either data available to be read (read) or if data can be written without blocking (write). Returns a corresponding Boolean value ('1' or '0'). If the underlying implementation does not support polling, an error is generated.
stream read
Usage
stream read [n]
Returns
A string of bytes read from the stream.

Reads data from the stream. If n is omitted, then this function will read all available data up to an "end-of-file" condition. If n is specified, then any available data up to n bytes are read. The read data is returned as a string.

Note that given a size to read n, it is valid for this function to return a string that has fewer than n bytes yet not be at the "end-of-file". See readblock below for a method by which to read a precise number of bytes.

stream readblock
Usage
stream readblock n [var]
Returns
A string containing the data (if var is not specified) or a boolean value (true if read successfully, false if not) (if var is specified).

Reads exactly n bytes from the stream. If the stream is currently in an "end-of-file" condition, then an empty string is returned (regardless of whether or not var is specified). Otherwise, if n bytes cannot be read, then an error is generated.

If var is not specified, then the read data is returned or a blank string is returned if an "end-of-file" was encountered. If var is specified, then the read data is stored in the variable var in the current context and returns a Boolean value indicating whether or not a block was read ('1' if a block was stored in var or '0' if an "end-of-file" was encountered at the beginning of the block).

Note that an "end-of-file" is only recognized as such if it occurs before any characters are actually read. If an "end-of-file" is encountered in the middle of a block it is treated as a "short block" error.

stream readln
Usage
stream readln [var]
Returns
A string containing the data (if var is not specified) or a boolean value (true if read successfully, false if not) (if var is specified).
Reads the next line from the given stream. If var is not specified then the line that was read is returned, or an error is generated if an "end-of-file" is encountered. If var is specified then the line is stored in the variable var in the current context and a Boolean value is returned to indicate whether or not a line was read ('1' indicates a line was read and stored in var and '0' indicates that an "end-of-file" was encountered).
stream write
Usage
stream write string
Returns
string
Writes the given string to the stream.
stream writeln
Usage
stream writeln string
Returns
string
Writes the given string to the stream followed by a newline character.