Handle objects used by Whatpm

Introduction

Some modules of Whatpm uses handle (filehandle or IO::Handle) like objects to represents various kinds of input streams. This document describes interfaces of handle objects used by them.

Interfaces

Character stream input handles

An object implementing the character stream input interface is expected to provides a character stream input. It has to exposes at least the following methods:

close ()
Close the stream. Once the stream is closed, read and manakai_read_until methods should not be invoked. If called, the result is undefined.
onerror ([CODE])
On getting, i.e. no argument is specified, return the error handler function, if it is explicitly specified, or undef otherwise. Handle objects might define the default error handler. Even if the default error handler is set as the error handler, i.e. no explicit error handler is set, undef is returned.

On setting, i.e. an argument is specified, the specified value is set as the error handler. It has to be a CODE reference; otherwise, the behavior of the handle object is undefined. As a special case, if undef is specified as the new value, any explicitly specified error handler is unset and the default error handler, if any, is set.

@@ The error handler would ...

read (SCALAR, LENGTH, [OFFSET])
Read characters from the input stream. This method should behave in a similar manner as the read method of a IO::Handle object that provides a character stream, except when the OFFSET argument is a negative value, in which case the result is undefined.
manakai_read_until (SCALAR, PATTERN, [OFFSET])
Read characters from the input stream, like the read method, but the number of read characters are not specified by length, but determined by the pattern match. Any character matching the regular expression PATTERN is read. The number of read characters is returned. If no character matches the PATTERN, then no character is read and zero (0) is returned. Note that the method don't have to return all characters matching the PATTERN once; for example, the method may decide to stop reading when the 256th character is read. The OFFSET argument, if specified, must be greater than or equal to zero (0); otherwise, the result is undefined.

Following classes are implementing this interface:

Following method arguments expects objects with this interface:

Byte stream input handles

An object implementing the byte stream input interface is expected to provides a byte (or octet) stream input. It has to exposes at least the following methods:

close
Close the stream. Once the stream is closed, the read method should not be invoked. If called, the results is undefined.
read (SCALAR, LENGTH, [OFFSET])
Read characters from the input stream. This method should behave in a similar manner as the read method of a IO::Handle object that provides a byte stream, except when the OFFSET argument is a negative value, in which case the result is undefined.

Following classes are implementing this interface:

In addition, an IO::Handle object (i.e. an object-oriented representation of Perl handles) can be used where this interface is expected, since the object has the methods mandated by this interface.

Following method arguments expects objects with this interface:

License

Copyright 2008 <wakaba@suikawiki.org>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.