Whatpm/Charset/handles.en.html

<!DOCTYPE HTML>
<html lang=en>
<head>
<title>Handle objects used by Whatpm</title>
<link rel=stylesheet href="http://suika.fam.cx/www/style/html/xhtml">
<link rel=author title=Wakaba href="http://suika.fam.cx/~wakaba/who?" lang=ja>
<link rel=license href="#license">
<link rel=top href="../../readme">
</head>
<body>
<h1>Handle objects used by Whatpm</h1>

<div class=section id=intro>
<h2>Introduction</h2>

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

<div class=section id=interfaces>
<h2>Interfaces</h2>

<div class=section id=interface-charstream-input>
<h3>Character stream input handles</h3>

<p>An object implementing the <dfn
id=term-charstream-input-interface>character stream input
interface</dfn> is expected to provides a character stream input.  It
has to exposes at least the following methods:

<dl>
<dt id=charstream-input-close><code>close ()</code>
  <dd>Close the stream.  Once the stream is closed, <code>read</code> and
  <code>manakai_read_until</code> methods should not be invoked.  If called,
  the result is undefined.
<dt id=charstream-input-onerror><code>onerror ([<var>CODE</var>])</code>
  <dd>On getting, i.e. no argument is specified, return the error handler
  function, if it is explicitly specified, or <code>undef</code> 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, <code>undef</code> is returned.
  
  <p>On setting, i.e. an argument is specified, the specified value is set
  as the error handler.  It has to be a <code>CODE</code> reference; otherwise,
  the behavior of the handle object is undefined.  As a special case, if 
  <code>undef</code> is specified as the new value, any explicitly specified
  error handler is unset and the default error handler, if any, is set.

  <p class=ed>@@ The error handler would ...
<dt id=charstream-input-read><code>read (<var>SCALAR</var>, <var>LENGTH</var>, [<var>OFFSET</var>])</code>
  <dd>Read characters from the input stream.  This method should behave in 
  a similar manner as the <code>read</code> method of a <code>IO::Handle</code>
  object that provides a character stream, except when the <var>OFFSET</var>
  argument is a negative value, in which case the result is undefined.
<dt id=charstream-input-manakai-read-until><code>manakai_read_until (<var>SCALAR</var>, <var>PATTERN</var>, [<var>OFFSET</var>])</code>
  <dd>Read characters from the input stream, like the 
  <a href="#charstream-input-read"><code>read</code></a> method,
  but the number of read characters are not specified by length, but
  determined by the pattern match.  Any character matching the regular
  expression <var>PATTERN</var> is read.  The number of read characters is
  returned.  If no character matches the <var>PATTERN</var>, then no character
  is read and zero (<code>0</code>) is returned.  Note that the method don't
  have to return all characters matching the <var>PATTERN</var> once; for
  example, the method may decide to stop reading when the 256th character
  is read.  The <var>OFFSET</var> argument, if specified, must be greater than
  or equal to zero (<code>0</code>); otherwise, the result is undefined.
</dl>

<p>Following classes are implementing this interface:
  <ul>
  <li><a href=DecodeHandle.html><code>Whatpm::Charset::DecodeHandle::CharString</code></a>
      (The class method
      <code>Whatpm::Charset::DecodeHandle::CharString->new</code>
      would generate an instance of this class.)
  <li><a href=DecodeHandle.html><code>Whatpm::Charset::DecodeHandle::Encode</code></a>
      (The <code>get_decode_handle</code> method on a 
      <code>Message::Charset::Info</code> object would generate an instance of
      this class.)
  <li><a href=DecodeHandle.html><code>Whatpm::Charset::DecodeHandle::ISO2022JP</code></a>
      (The <code>get_decode_handle</code> method on a 
      <code>Message::Charset::Info</code> object would generate an instance of
      this class.)
  <li><a href=UnicodeChecker.html><code>Whatpm::Charset::UnicodeChecker</code></a>
      (The class method
      <code>Whatpm::Charset::UnicodeChecker->new_handle</code>
      would generate an instance of this class.)
  </ul>

<p>Following method arguments expects objects with this interface:
  <ul>
  <li>The first argument of the
      <a href="../HTML.html#item_parse_char_stream"><code>parse_char_stream</code></a>
      method of <a href="../HTML.html"><code>Whatpm::HTML</code></a> objects
  <li>The first argument of the <code>new_handle</code> method of
      the <a href="UnicodeChecker.html"><code>Whatpm::Charset::UnicodeChecker</code></a>
      class
  </ul>

<!--
Required (provided) methods:
  Whatpm::HTML->parse_char_stream: read, manakai_read_until
  Whatpm::HTML->parse_byte_stream: onerror [+ parse_char_stream]
  Whatpm::Charset::UnicodeChecker: read, manakai_read_until, close,
      charset, has_bom, input_encoding, onerror
      (+ ungetc, new_handle)
  Whatpm::Charset::DecodeHandle::CharString: (new, getc, read,
      manakai_read_until, ungetc, onerror, close)
  Whatpm::Charset::DecodeHandle::Encode: (charset, close, getc, read,
      manakai_read_until, has_bom, input_encoding, input_encoding, ungetc)
  Whatpm::Charset::DecodeHandle::ISO2022JP: (getc, read, manakai_read_until
      [+ Whatpm::Charset::DecodeHandle::Encode])
  Message::DOM::XMLParserTemp: getc, ungetc, input_encoding, close
  WebHACC::Language::Base: onerror, read
-->

</div>

<div class=section id=interface-bytestream-input>
<h3>Byte stream input handles</h3>

<p>An object implementing the <dfn
id=term-bytestream-input-interface>byte stream input interface</dfn>
is expected to provides a byte (or octet) stream input.  It has to
exposes at least the following methods:

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

<p>Following classes are implementing this interface:
  <ul>
  <li><a href="DecodeHandle.html"><code>Whatpm::Charset::DecodeHandle::ByteBuffer</code></a>
      (The class method
      <code>Whatpm::Charset::DecodeHandle::ByteBuffer->new</code>
      would generate an instance of this class.)
  </ul>

<p>In addition, an <code>IO::Handle</code> 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.

<p>Following method arguments expects objects with this interface:
  <ul>
  <li>The first argument of the <code>get_decode_handle</code> method of
      <code>Message::Charset::Info</code> objects
  </ul>

<!--
  Whatpm::Charset::DecodeHandle::ByteBuffer: read, close
      (new, read, close)
  Whatpm::Charset::DecodeHandle::Encode: close, read
  Whatpm::Charset::DecodeHandle::ISO2022JP: read
      [+ Whatpm::Charset::DecodeHandle::Encode]
  Whatpm::Charset::DecodeHandle->create_decode_handle: read
  Message::Charset::Info->get_decode_handle:
      [+ Whatpm::Charset::DecodeHandle::*]
-->

</div>

</div>

<div class=section id=license>
<h2>License</h2>

<p>Copyright 2008 <a href="http://suika.fam.cx/~wakaba/who?"
rel=author lang=ja>Wakaba</a> <code class=mail>&lt;<a
href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></code>

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

</div>

</body>
</html>
1	wakaba	1.1	<!DOCTYPE HTML>
2			<html lang=en>
3			<head>
4			<title>Handle objects used by Whatpm</title>
5			<link rel=stylesheet href="http://suika.fam.cx/www/style/html/xhtml">
6			<link rel=author title=Wakaba href="http://suika.fam.cx/~wakaba/who?" lang=ja>
7			<link rel=license href="#license">
8			<link rel=top href="../../readme">
9			</head>
10			<body>
11			<h1>Handle objects used by Whatpm</h1>
12
13			<div class=section id=intro>
14			<h2>Introduction</h2>
15
16			<p>Some modules of Whatpm uses handle (filehandle or <code>IO::Handle</code>)
17			like objects to represents various kinds of input streams.
18			This document describes interfaces of handle objects used by them.
19			</div>
20
21			<div class=section id=interfaces>
22			<h2>Interfaces</h2>
23
24			<div class=section id=interface-charstream-input>
25			<h3>Character stream input handles</h3>
26
27			<p>An object implementing the <dfn
28			id=term-charstream-input-interface>character stream input
29			interface</dfn> is expected to provides a character stream input. It
30			has to exposes at least the following methods:
31
32			<dl>
33			<dt id=charstream-input-close><code>close ()</code>
34			<dd>Close the stream. Once the stream is closed, <code>read</code> and
35			<code>manakai_read_until</code> methods should not be invoked. If called,
36			the result is undefined.
37			<dt id=charstream-input-onerror><code>onerror ([<var>CODE</var>])</code>
38			<dd>On getting, i.e. no argument is specified, return the error handler
39			function, if it is explicitly specified, or <code>undef</code> otherwise.
40			Handle objects might define the default error handler. Even if the default
41			error handler is set as the error handler, i.e. no explicit error handler
42			is set, <code>undef</code> is returned.
43
44			<p>On setting, i.e. an argument is specified, the specified value is set
45			as the error handler. It has to be a <code>CODE</code> reference; otherwise,
46			the behavior of the handle object is undefined. As a special case, if
47			<code>undef</code> is specified as the new value, any explicitly specified
48			error handler is unset and the default error handler, if any, is set.
49
50			<p class=ed>@@ The error handler would ...
51			<dt id=charstream-input-read><code>read (<var>SCALAR</var>, <var>LENGTH</var>, [<var>OFFSET</var>])</code>
52			<dd>Read characters from the input stream. This method should behave in
53			a similar manner as the <code>read</code> method of a <code>IO::Handle</code>
54			object that provides a character stream, except when the <var>OFFSET</var>
55			argument is a negative value, in which case the result is undefined.
56			<dt id=charstream-input-manakai-read-until><code>manakai_read_until (<var>SCALAR</var>, <var>PATTERN</var>, [<var>OFFSET</var>])</code>
57			<dd>Read characters from the input stream, like the
58			<a href="#charstream-input-read"><code>read</code></a> method,
59			but the number of read characters are not specified by length, but
60			determined by the pattern match. Any character matching the regular
61			expression <var>PATTERN</var> is read. The number of read characters is
62			returned. If no character matches the <var>PATTERN</var>, then no character
63			is read and zero (<code>0</code>) is returned. Note that the method don't
64			have to return all characters matching the <var>PATTERN</var> once; for
65			example, the method may decide to stop reading when the 256th character
66			is read. The <var>OFFSET</var> argument, if specified, must be greater than
67			or equal to zero (<code>0</code>); otherwise, the result is undefined.
68			</dl>
69
70			<p>Following classes are implementing this interface:
71			<ul>
72			<li><a href=DecodeHandle.html><code>Whatpm::Charset::DecodeHandle::CharString</code></a>
73			(The class method
74			<code>Whatpm::Charset::DecodeHandle::CharString->new</code>
75			would generate an instance of this class.)
76			<li><a href=DecodeHandle.html><code>Whatpm::Charset::DecodeHandle::Encode</code></a>
77			(The <code>get_decode_handle</code> method on a
78			<code>Message::Charset::Info</code> object would generate an instance of
79			this class.)
80			<li><a href=DecodeHandle.html><code>Whatpm::Charset::DecodeHandle::ISO2022JP</code></a>
81			(The <code>get_decode_handle</code> method on a
82			<code>Message::Charset::Info</code> object would generate an instance of
83			this class.)
84			<li><a href=UnicodeChecker.html><code>Whatpm::Charset::UnicodeChecker</code></a>
85			(The class method
86			<code>Whatpm::Charset::UnicodeChecker->new_handle</code>
87			would generate an instance of this class.)
88			</ul>
89
90			<p>Following method arguments expects objects with this interface:
91			<ul>
92			<li>The first argument of the
93			<a href="../HTML.html#item_parse_char_stream"><code>parse_char_stream</code></a>
94			method of <a href="../HTML.html"><code>Whatpm::HTML</code></a> objects
95			<li>The first argument of the <code>new_handle</code> method of
96			the <a href="UnicodeChecker.html"><code>Whatpm::Charset::UnicodeChecker</code></a>
97			class
98			</ul>
99
100			<!--
101			Required (provided) methods:
102			Whatpm::HTML->parse_char_stream: read, manakai_read_until
103			Whatpm::HTML->parse_byte_stream: onerror [+ parse_char_stream]
104			Whatpm::Charset::UnicodeChecker: read, manakai_read_until, close,
105			charset, has_bom, input_encoding, onerror
106			(+ ungetc, new_handle)
107			Whatpm::Charset::DecodeHandle::CharString: (new, getc, read,
108			manakai_read_until, ungetc, onerror, close)
109			Whatpm::Charset::DecodeHandle::Encode: (charset, close, getc, read,
110			manakai_read_until, has_bom, input_encoding, input_encoding, ungetc)
111			Whatpm::Charset::DecodeHandle::ISO2022JP: (getc, read, manakai_read_until
112			[+ Whatpm::Charset::DecodeHandle::Encode])
113			Message::DOM::XMLParserTemp: getc, ungetc, input_encoding, close
114			WebHACC::Language::Base: onerror, read
115			-->
116
117			</div>
118
119			<div class=section id=interface-bytestream-input>
120			<h3>Byte stream input handles</h3>
121
122			<p>An object implementing the <dfn
123			id=term-bytestream-input-interface>byte stream input interface</dfn>
124			is expected to provides a byte (or octet) stream input. It has to
125			exposes at least the following methods:
126
127			<dl>
128			<dt id=bytestream-input-close><code>close</code>
129			<dd>Close the stream. Once the stream is closed, the <code>read</code>
130			method should not be invoked. If called, the results is undefined.
131			<dt id=bytestream-input-read><code>read (<var>SCALAR</var>, <var>LENGTH</var>, [<var>OFFSET</var>])</code>
132			<dd>Read characters from the input stream. This method should behave in
133			a similar manner as the <code>read</code> method of a <code>IO::Handle</code>
134			object that provides a byte stream, except when the <var>OFFSET</var>
135			argument is a negative value, in which case the result is undefined.
136			</dl>
137
138			<p>Following classes are implementing this interface:
139			<ul>
140			<li><a href="DecodeHandle.html"><code>Whatpm::Charset::DecodeHandle::ByteBuffer</code></a>
141			(The class method
142			<code>Whatpm::Charset::DecodeHandle::ByteBuffer->new</code>
143			would generate an instance of this class.)
144			</ul>
145
146			<p>In addition, an <code>IO::Handle</code> object (i.e. an
147			object-oriented representation of Perl handles) can be used where this
148			interface is expected, since the object has the methods mandated by
149			this interface.
150
151			<p>Following method arguments expects objects with this interface:
152			<ul>
153			<li>The first argument of the <code>get_decode_handle</code> method of
154			<code>Message::Charset::Info</code> objects
155			</ul>
156
157			<!--
158			Whatpm::Charset::DecodeHandle::ByteBuffer: read, close
159			(new, read, close)
160			Whatpm::Charset::DecodeHandle::Encode: close, read
161			Whatpm::Charset::DecodeHandle::ISO2022JP: read
162			[+ Whatpm::Charset::DecodeHandle::Encode]
163			Whatpm::Charset::DecodeHandle->create_decode_handle: read
164			Message::Charset::Info->get_decode_handle:
165			[+ Whatpm::Charset::DecodeHandle::*]
166			-->
167
168			</div>
169
170			</div>
171
172			<div class=section id=license>
173			<h2>License</h2>
174
175			<p>Copyright 2008 <a href="http://suika.fam.cx/~wakaba/who?"
176			rel=author lang=ja>Wakaba</a> <code class=mail><<a
177			href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></code>
178
179			<p>This library is free software; you can redistribute it and/or
180			modify it under the same terms as Perl itself.
181
182			</div>
183
184			</body>
185			</html>