whatpm/Whatpm/WebIDL.html

<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Whatpm::WebIDL - A WebIDL Parser and Conformance Checker</title>
<link rel="stylesheet" href="http://suika.fam.cx/www/style/html/pod.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:wakaba@suika.fam.cx" />
</head>

<body>


<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>

<ul>

        <li><a href="#name">NAME</a></li>
        <li><a href="#synopsis">SYNOPSIS</a></li>
        <li><a href="#description">DESCRIPTION</a></li>
        <li><a href="#methods">METHODS</a></li>
        <ul>

                <li><a href="#whatpm__webidl__parser"><code>Whatpm::WebIDL::Parser</code></a></li>
                <li><a href="#whatpm__webidl__definitions"><code>Whatpm::WebIDL::Definitions</code></a></li>
        </ul>

        <li><a href="#see_also">SEE ALSO</a></li>
        <li><a href="#author">AUTHOR</a></li>
        <li><a href="#license">LICENSE</a></li>
</ul>

<hr name="index" />
</div>
<!-- INDEX END -->

<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Whatpm::WebIDL - A WebIDL Parser and Conformance Checker</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
  use Whatpm::WebIDL;
  
  my $parser = Whatpm::WebIDL::Parser-&gt;new;
  my $onerror = sub {
    my %arg = @_;
    warn join &quot;\t&quot;,
        $arg{line}, $arg{column}, $arg{level},
        $arg{type}, $arg{text} // '', $arg{value} // '';
  };
  
  my $webidl_doc = $parser-&gt;parse_char_string ($webidl_string, $onerror);
  $webidl_doc-&gt;check ($onerror);</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The <code>Whatpm::WebIDL</code> module provides a WebIDL parser, as well as a
conformance checker that can be invoked once an IDL fragment has been
parsed.</p>
<p>This is an implementation of W3C Web IDL specification.</p>
<p>
</p>
<hr />
<h1><a name="methods">METHODS</a></h1>
<p>The <code>Whatpm::WebIDL</code> package itself provides no functionality.  It
contains various packages including <code>Whatpm::WebIDL::Parser</code>.</p>
<p>
</p>
<h2><a name="whatpm__webidl__parser"><code>Whatpm::WebIDL::Parser</code></a></h2>
<p>The <code>Whatpm::WebIDL::Parser</code> package, which is contained in the
<code>Whatpm::WebIDL</code> module, defines a class method and an instance
method:</p>
<dl>
<dt><strong><a name="new" class="item"><em>$parser</em> = Whatpm::WebIDL::Parser-&gt;new;</a></strong>

<dd>
<p>This class method creates a new instance of the WebIDL parser.</p>
</dd>
</li>
<dt><strong><a name="parse_char_string" class="item"><em>$webidl_doc</em> = <em>$parser</em>-&gt;parse_char_string (<em>$webidl_fragment</em>, [<em>$onerror</em>]);</a></strong>

<dd>
<p>This instance method of the <em>$parser</em> method parses a WebIDL fragment
and returns its in-memory representation.</p>
</dd>
<dd>
<p>The first argument, <em>$webidl_fragment</em>, is the IDL fragment to be
parsed.  It must be a string of characters (not bytes).</p>
</dd>
<dd>
<p>As the second argument, <em>$onerror</em>, a <code>CODE</code> reference may be
specified.  If specified, whenever a parse error is found, or a
warning message is raised, the <code>CODE</code> is invoked with arguments
describing the error. @@ TODO: ref to degtailed description</p>
</dd>
<dd>
<p>Note that the W3C WebIDL specification does not define how invalid
WebIDL fragments are parsed.  This parse implements a foward
compatible parsing rule that is similar to the CSS parsing rule; once
a parse error is found, everything until the next <code>;</code> character (or
the end-of-file, if there is no <code>;</code> character) is ignored, taking
pairs of <code>{</code> and <code>}</code> characters into account.  If a fragment
prematurely ends inside a block, then a <code>};</code> sequence that closes the
block is implied.  Any error that does not violate the grammer, e.g.
any reference to an undefined interface, does not stop the parser; to
detect such errors, the <code>checker</code> has to be invoked later.</p>
</dd>
<dd>
<p>The returned object, <code>$webidl_doc</code>, is an in-memory representation of
the prased IDL fragment.  It is an instance of the
<code>Whatpm::WebIDL::Definitions</code> class.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="whatpm__webidl__definitions"><code>Whatpm::WebIDL::Definitions</code></a></h2>
<p>An object of the <code>Whatpm::WebIDL::Definitions</code> class represents a
WebIDL fragment (or <code>Definitions</code> production in the WebIDL
specification).</p>
<dl>
<dt><strong><a name="check" class="item"><em>$webidl_doc</em>-&gt;check (<em>$onerror</em>, [<em>$levels</em>]);</a></strong>

<dd>
<p>This method checks the conformance of the WebIDL objects,
<em>$webidl_docs</em>.</p>
</dd>
<dd>
<p>@@ TODO: documentation for <em>$onerror</em> and <em>$levels</em>.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p>WebIDL Editor's Draft
&lt;http://dev.w3.org/cvsweb/~checkout~/2006/webapi/WebIDL/Overview.html?content-type=text/html;%20charset=utf-8&gt;</p>
<p><code>WebHACC::Language::WebIDL</code> module, as an example of the usage of
this module
&lt;http://suika.fam.cx/gate/cvs/webroot/gate/2007/html/WebHACC/Language/WebIDL.pm&gt;</p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Wakaba &lt;<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>&gt;</p>
<p>
</p>
<hr />
<h1><a name="license">LICENSE</a></h1>
<p>Copyright 2008 Wakaba &lt;<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>&gt;</p>
<p>This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.</p>

</body>

</html>
1	<?xml version="1.0" ?>
2	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3	<html xmlns="http://www.w3.org/1999/xhtml">
4	<head>
5	<title>Whatpm::WebIDL - A WebIDL Parser and Conformance Checker</title>
6	<link rel="stylesheet" href="http://suika.fam.cx/www/style/html/pod.css" type="text/css" />
7	<meta http-equiv="content-type" content="text/html; charset=utf-8" />
8	<link rev="made" href="mailto:wakaba@suika.fam.cx" />
9	</head>
10
11	<body>
12
13
14	<!-- INDEX BEGIN -->
15	<div name="index">
16	<p><a name="__index__"></a></p>
17
18	<ul>
19
20	<li><a href="#name">NAME</a></li>
21	<li><a href="#synopsis">SYNOPSIS</a></li>
22	<li><a href="#description">DESCRIPTION</a></li>
23	<li><a href="#methods">METHODS</a></li>
24	<ul>
25
26	<li><a href="#whatpm__webidl__parser"><code>Whatpm::WebIDL::Parser</code></a></li>
27	<li><a href="#whatpm__webidl__definitions"><code>Whatpm::WebIDL::Definitions</code></a></li>
28	</ul>
29
30	<li><a href="#see_also">SEE ALSO</a></li>
31	<li><a href="#author">AUTHOR</a></li>
32	<li><a href="#license">LICENSE</a></li>
33	</ul>
34
35	<hr name="index" />
36	</div>
37	<!-- INDEX END -->
38
39	<p>
40	</p>
41	<h1><a name="name">NAME</a></h1>
42	<p>Whatpm::WebIDL - A WebIDL Parser and Conformance Checker</p>
43	<p>
44	</p>
45	<hr />
46	<h1><a name="synopsis">SYNOPSIS</a></h1>
47	<pre>
48	use Whatpm::WebIDL;
49
50	my $parser = Whatpm::WebIDL::Parser->new;
51	my $onerror = sub {
52	my %arg = @_;
53	warn join "\t",
54	$arg{line}, $arg{column}, $arg{level},
55	$arg{type}, $arg{text} // '', $arg{value} // '';
56	};
57
58	my $webidl_doc = $parser->parse_char_string ($webidl_string, $onerror);
59	$webidl_doc->check ($onerror);</pre>
60	<p>
61	</p>
62	<hr />
63	<h1><a name="description">DESCRIPTION</a></h1>
64	<p>The <code>Whatpm::WebIDL</code> module provides a WebIDL parser, as well as a
65	conformance checker that can be invoked once an IDL fragment has been
66	parsed.</p>
67	<p>This is an implementation of W3C Web IDL specification.</p>
68	<p>
69	</p>
70	<hr />
71	<h1><a name="methods">METHODS</a></h1>
72	<p>The <code>Whatpm::WebIDL</code> package itself provides no functionality. It
73	contains various packages including <code>Whatpm::WebIDL::Parser</code>.</p>
74	<p>
75	</p>
76	<h2><a name="whatpm__webidl__parser"><code>Whatpm::WebIDL::Parser</code></a></h2>
77	<p>The <code>Whatpm::WebIDL::Parser</code> package, which is contained in the
78	<code>Whatpm::WebIDL</code> module, defines a class method and an instance
79	method:</p>
80	<dl>
81	<dt><strong><a name="new" class="item"><em>$parser</em> = Whatpm::WebIDL::Parser->new;</a></strong>
82
83	<dd>
84	<p>This class method creates a new instance of the WebIDL parser.</p>
85	</dd>
86	</li>
87	<dt><strong><a name="parse_char_string" class="item"><em>$webidl_doc</em> = <em>$parser</em>->parse_char_string (<em>$webidl_fragment</em>, [<em>$onerror</em>]);</a></strong>
88
89	<dd>
90	<p>This instance method of the <em>$parser</em> method parses a WebIDL fragment
91	and returns its in-memory representation.</p>
92	</dd>
93	<dd>
94	<p>The first argument, <em>$webidl_fragment</em>, is the IDL fragment to be
95	parsed. It must be a string of characters (not bytes).</p>
96	</dd>
97	<dd>
98	<p>As the second argument, <em>$onerror</em>, a <code>CODE</code> reference may be
99	specified. If specified, whenever a parse error is found, or a
100	warning message is raised, the <code>CODE</code> is invoked with arguments
101	describing the error. @@ TODO: ref to degtailed description</p>
102	</dd>
103	<dd>
104	<p>Note that the W3C WebIDL specification does not define how invalid
105	WebIDL fragments are parsed. This parse implements a foward
106	compatible parsing rule that is similar to the CSS parsing rule; once
107	a parse error is found, everything until the next <code>;</code> character (or
108	the end-of-file, if there is no <code>;</code> character) is ignored, taking
109	pairs of <code>{</code> and <code>}</code> characters into account. If a fragment
110	prematurely ends inside a block, then a <code>};</code> sequence that closes the
111	block is implied. Any error that does not violate the grammer, e.g.
112	any reference to an undefined interface, does not stop the parser; to
113	detect such errors, the <code>checker</code> has to be invoked later.</p>
114	</dd>
115	<dd>
116	<p>The returned object, <code>$webidl_doc</code>, is an in-memory representation of
117	the prased IDL fragment. It is an instance of the
118	<code>Whatpm::WebIDL::Definitions</code> class.</p>
119	</dd>
120	</li>
121	</dl>
122	<p>
123	</p>
124	<h2><a name="whatpm__webidl__definitions"><code>Whatpm::WebIDL::Definitions</code></a></h2>
125	<p>An object of the <code>Whatpm::WebIDL::Definitions</code> class represents a
126	WebIDL fragment (or <code>Definitions</code> production in the WebIDL
127	specification).</p>
128	<dl>
129	<dt><strong><a name="check" class="item"><em>$webidl_doc</em>->check (<em>$onerror</em>, [<em>$levels</em>]);</a></strong>
130
131	<dd>
132	<p>This method checks the conformance of the WebIDL objects,
133	<em>$webidl_docs</em>.</p>
134	</dd>
135	<dd>
136	<p>@@ TODO: documentation for <em>$onerror</em> and <em>$levels</em>.</p>
137	</dd>
138	</li>
139	</dl>
140	<p>
141	</p>
142	<hr />
143	<h1><a name="see_also">SEE ALSO</a></h1>
144	<p>WebIDL Editor's Draft
145	<http://dev.w3.org/cvsweb/~checkout~/2006/webapi/WebIDL/Overview.html?content-type=text/html;%20charset=utf-8></p>
146	<p><code>WebHACC::Language::WebIDL</code> module, as an example of the usage of
147	this module
148	<http://suika.fam.cx/gate/cvs/webroot/gate/2007/html/WebHACC/Language/WebIDL.pm></p>
149	<p>
150	</p>
151	<hr />
152	<h1><a name="author">AUTHOR</a></h1>
153	<p>Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></p>
154	<p>
155	</p>
156	<hr />
157	<h1><a name="license">LICENSE</a></h1>
158	<p>Copyright 2008 Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></p>
159	<p>This library is free software; you can redistribute it
160	and/or modify it under the same terms as Perl itself.</p>
161
162	</body>
163
164	</html>