Handle objects used by Whatpm

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:

• Whatpm::Charset::DecodeHandle::CharString (The class method Whatpm::Charset::DecodeHandle::CharString->new would generate an instance of this class.)
• Whatpm::Charset::DecodeHandle::Encode (The get_decode_handle method on a Message::Charset::Info object would generate an instance of this class.)
• Whatpm::Charset::DecodeHandle::ISO2022JP (The get_decode_handle method on a Message::Charset::Info object would generate an instance of this class.)
• Whatpm::Charset::UnicodeChecker (The class method Whatpm::Charset::UnicodeChecker->new_handle would generate an instance of this class.)

Following method arguments expects objects with this interface:

• The first argument of the parse_char_stream method of Whatpm::HTML objects
• The first argument of the new_handle method of the Whatpm::Charset::UnicodeChecker class

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:

• Whatpm::Charset::DecodeHandle::ByteBuffer (The class method Whatpm::Charset::DecodeHandle::ByteBuffer->new would generate an instance of this class.)

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:

• The first argument of the get_decode_handle method of Message::Charset::Info objects