whatpm/Whatpm/WebIDL.pod

=head1 NAME

Whatpm::WebIDL - A WebIDL Parser and Conformance Checker

=head1 SYNOPSIS

  use Whatpm::WebIDL;
  
  my $parser = Whatpm::WebIDL::Parser->new;
  my $onerror = sub {
    my %arg = @_;
    warn join "\t",
        $arg{line}, $arg{column}, $arg{level},
        $arg{type}, $arg{text} // '', $arg{value} // '';
  };
  
  my $webidl_doc = $parser->parse_char_string ($webidl_string, $onerror);
  $webidl_doc->check ($onerror);

=head1 DESCRIPTION

The C<Whatpm::WebIDL> module provides a WebIDL parser, as well as a
conformance checker that can be invoked once an IDL fragment has been
parsed.

This is an implementation of W3C Web IDL specification.

=head1 METHODS

The C<Whatpm::WebIDL> package itself provides no functionality.  It
contains various packages including C<Whatpm::WebIDL::Parser>.

=head2 C<Whatpm::WebIDL::Parser>

The C<Whatpm::WebIDL::Parser> package, which is contained in the
C<Whatpm::WebIDL> module, defines a class method and an instance
method:

=over 4

=item I<$parser> = Whatpm::WebIDL::Parser->new;

This class method creates a new instance of the WebIDL parser.

=item I<$webidl_doc> = I<$parser>->parse_char_string (I<$webidl_fragment>, [I<$onerror>]);

This instance method of the I<$parser> method parses a WebIDL fragment
and returns its in-memory representation.

The first argument, I<$webidl_fragment>, is the IDL fragment to be
parsed.  It must be a string of characters (not bytes).

As the second argument, I<$onerror>, a C<CODE> reference may be
specified.  If specified, whenever a parse error is found, or a
warning message is raised, the C<CODE> is invoked with arguments
describing the error. @@ TODO: ref to degtailed description

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 C<;> character (or
the end-of-file, if there is no C<;> character) is ignored, taking
pairs of C<{> and C<}> characters into account.  If a fragment
prematurely ends inside a block, then a C<};> 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 C<checker> has to be invoked later.

The returned object, C<$webidl_doc>, is an in-memory representation of
the prased IDL fragment.  It is an instance of the
C<Whatpm::WebIDL::Definitions> class.

=back

=head2 C<Whatpm::WebIDL::Definitions>

An object of the C<Whatpm::WebIDL::Definitions> class represents a
WebIDL fragment (or C<Definitions> production in the WebIDL
specification).

=over 4

=item I<$webidl_doc>->check (I<$onerror>, [I<$levels>]);

This method checks the conformance of the WebIDL objects,
I<$webidl_docs>.

@@ TODO: documentation for I<$onerror> and I<$levels>.

=back

=head1 SEE ALSO

WebIDL Editor's Draft
<http://dev.w3.org/cvsweb/~checkout~/2006/webapi/WebIDL/Overview.html?content-type=text/html;%20charset=utf-8>

C<WebHACC::Language::WebIDL> module, as an example of the usage of
this module
<http://suika.fam.cx/gate/cvs/webroot/gate/2007/html/WebHACC/Language/WebIDL.pm>

=head1 AUTHOR

Wakaba <w@suika.fam.cx>

=head1 LICENSE

Copyright 2008 Wakaba <w@suika.fam.cx>

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

=cut

# $Date:$
1	wakaba	1.1	=head1 NAME
2
3			Whatpm::WebIDL - A WebIDL Parser and Conformance Checker
4
5			=head1 SYNOPSIS
6
7			use Whatpm::WebIDL;
8
9			my $parser = Whatpm::WebIDL::Parser->new;
10			my $onerror = sub {
11			my %arg = @_;
12			warn join "\t",
13			$arg{line}, $arg{column}, $arg{level},
14			$arg{type}, $arg{text} // '', $arg{value} // '';
15			};
16
17			my $webidl_doc = $parser->parse_char_string ($webidl_string, $onerror);
18			$webidl_doc->check ($onerror);
19
20			=head1 DESCRIPTION
21
22			The C<Whatpm::WebIDL> module provides a WebIDL parser, as well as a
23			conformance checker that can be invoked once an IDL fragment has been
24			parsed.
25
26			This is an implementation of W3C Web IDL specification.
27
28			=head1 METHODS
29
30			The C<Whatpm::WebIDL> package itself provides no functionality. It
31			contains various packages including C<Whatpm::WebIDL::Parser>.
32
33			=head2 C<Whatpm::WebIDL::Parser>
34
35			The C<Whatpm::WebIDL::Parser> package, which is contained in the
36			C<Whatpm::WebIDL> module, defines a class method and an instance
37			method:
38
39			=over 4
40
41			=item I<$parser> = Whatpm::WebIDL::Parser->new;
42
43			This class method creates a new instance of the WebIDL parser.
44
45			=item I<$webidl_doc> = I<$parser>->parse_char_string (I<$webidl_fragment>, [I<$onerror>]);
46
47			This instance method of the I<$parser> method parses a WebIDL fragment
48			and returns its in-memory representation.
49
50			The first argument, I<$webidl_fragment>, is the IDL fragment to be
51			parsed. It must be a string of characters (not bytes).
52
53			As the second argument, I<$onerror>, a C<CODE> reference may be
54			specified. If specified, whenever a parse error is found, or a
55			warning message is raised, the C<CODE> is invoked with arguments
56			describing the error. @@ TODO: ref to degtailed description
57
58			Note that the W3C WebIDL specification does not define how invalid
59			WebIDL fragments are parsed. This parse implements a foward
60			compatible parsing rule that is similar to the CSS parsing rule; once
61			a parse error is found, everything until the next C<;> character (or
62			the end-of-file, if there is no C<;> character) is ignored, taking
63			pairs of C<{> and C<}> characters into account. If a fragment
64			prematurely ends inside a block, then a C<};> sequence that closes the
65			block is implied. Any error that does not violate the grammer, e.g.
66			any reference to an undefined interface, does not stop the parser; to
67			detect such errors, the C<checker> has to be invoked later.
68
69			The returned object, C<$webidl_doc>, is an in-memory representation of
70			the prased IDL fragment. It is an instance of the
71			C<Whatpm::WebIDL::Definitions> class.
72
73			=back
74
75			=head2 C<Whatpm::WebIDL::Definitions>
76
77			An object of the C<Whatpm::WebIDL::Definitions> class represents a
78			WebIDL fragment (or C<Definitions> production in the WebIDL
79			specification).
80
81			=over 4
82
83			=item I<$webidl_doc>->check (I<$onerror>, [I<$levels>]);
84
85			This method checks the conformance of the WebIDL objects,
86			I<$webidl_docs>.
87
88			@@ TODO: documentation for I<$onerror> and I<$levels>.
89
90			=back
91
92			=head1 SEE ALSO
93
94			WebIDL Editor's Draft
95			<http://dev.w3.org/cvsweb/~checkout~/2006/webapi/WebIDL/Overview.html?content-type=text/html;%20charset=utf-8>
96
97			C<WebHACC::Language::WebIDL> module, as an example of the usage of
98			this module
99			<http://suika.fam.cx/gate/cvs/webroot/gate/2007/html/WebHACC/Language/WebIDL.pm>
100
101			=head1 AUTHOR
102
103			Wakaba <w@suika.fam.cx>
104
105			=head1 LICENSE
106
107			Copyright 2008 Wakaba <w@suika.fam.cx>
108
109			This library is free software; you can redistribute it
110			and/or modify it under the same terms as Perl itself.
111
112			=cut
113
114			# $Date:$