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	<!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>