ATTRIBUTES

$self->format

Returns the format used on the stream. Built-in formats are 'json' or 'storable'

METHODS

$data= $self->read

Returns one data record, or () at end of stream. This method can block, so don't use it if you wanted the nonblocking API. Note that undef could be encoded on the stream, making the return value slightly vague. Call it in array context if you want to see the difference between reading undef and EOF. However, keep in mind that undef makes a nice terminator between segments of data, so it is still good style to do:

while ($rec= $stream->read()) {
}

Read throws an exception if a partial record exists at the end of the stream.

(success, $data)= $self->extractNextRecord( $buffer )

This method is lower level than read(). It attempts to extract bytes out of the passed argument (which should be a scalar) and returns a success flag, and the data if it succeeds. As such, this should always be called in array context.

Note that there is no need to use the read buffer of this object; you are free to use whatever buffer you like. However, it also means you must grow your scalar large enough to hold an entire data record before this function will succeed.

The first time this method succeeds, it will have silently detected the format of the stream. You may then call ->format without fear of blocking.

EXTRACTION FUNCTIONS

The API for an extraction function is my ($dataStruct, $remainder)= $self->_extract_$FORMAT( $buffer );

This makes an extraction function very easy to write. - name the method "_extract_" . $format - return () if there is not enough data. - return ($dataStruct, $remainder) if the buffer contained a complete record. - die if there is enough data but the bytes can't be decoded. - $remainder should be an empty scalar if the entire buffer was used; NOT undef. - $data is allowed to be undef, if that's what the user originally wrote.