whatpm/Whatpm/HTML.pod

=head1 NAME

Whatpm::HTML - An HTML Parser and Serializer

=head1 SYNOPSIS

  use Whatpm::HTML;
  
  my $s = q<<!DOCTYPE html><html>...</html>>;
  # $doc = an empty DOM |Document| object
  my $on_error = sub {
    my %error = @_;
    warn $error{type}, "\n";
  };
  
  Whatpm::HTML->parse_char_string ($s => $doc, $onerror);
  
  ## Now, |$doc| is the DOM representation of |$s|.

=head1 DESCRIPTION

The C<Whatpm::HTML> module contains HTML parser and serializer.

The HTML parser can be used to construct the DOM tree representation
from an HTML document.  The parsing and tree construction are done 
as described in the Web Application 1.0 specification.

The HTML serializer can be used to obtain the HTML document representation
of a DOM tree (or a tree fragment thereof).  The serialization
is performed as described in the Web Applications 1.0 specification
for C<innerHTML> DOM attribute.

This module is part of Whatpm - Perl Modules for 
Web Hypertext Application Technologies.

=head1 METHODS

=over 4

=item [I<$doc> =] Whatpm::HTML->parse_char_string (I<$s>, I<$doc>[, I<$onerror>]);

Parse a string I<$s> as an HTML document.

The first argument, I<$s>, MUST be a string.  It is parsed
as a sequence of characters representing an HTML document.

The second argument, I<$doc>, MUST be an empty read-write 
DOM C<Document> object.  The HTML DOM tree is constructed
onto this C<Document> object.

The third argument, I<$onerror>, MUST be a reference to
the error handler code.  Whenever a parse error is detected,
this code is invoked with an argument that contains a
useless string that might describe what is wrong.
The code MAY throw an exception, so that whole the parsing
process aborts.  Otherwise, the parser will continue to
process the input.  The code MUST NOT modify I<$s> or I<$doc>.
If it does, then the result is undefined.
This argument is optional; if missing, any
parse error makes that string being C<warn>ed.

B<NOTE>: To be a conforming user agent, the code MUST either
abort the processing by throwing an exception at the first
invocation or MUST continue the processing until the parser
stops.

The method returns the DOM C<Document> object (i.e. the second argument).

Note that the C<Whatpm::NanoDOM> module provides a non-conforming
implementation of DOM that only implements a subset that
is necessary for the purpose of C<Whatpm::HTML>'s parsing and
serializing.
With this module, creating a new HTML C<Document> object
from a string containing HTML document might be coded as:

  use Whatpm::HTML;
  use Whatpm::NanoDOM;
  my $doc = Whatpm::HTML->parse_char_string
      ($s => Whatpm::NanoDOM::Document->new, $onerror);

=back

=head1 LOW-LEVEL INTERFACE

@@ TBW

=head2 Application Cache Selection Algorithm Hook

Once a parser I<$p> is instantiated by method C<new>, 
a C<CODE> reference can be set to C<< I<$p>->{application_cache_selection} >>.
That C<CODE> will be called back when the application cache selection
algorithm MUST be run per HTML5.  By default,
C<< I<$p>->{application_cache_selection} >> is set to an empty subroutine.

The subroutine will be invoked with an argument I<manifest_uri>, 
which is set to the manifest URI when the algorithm MUST be invoked
with a manifest URI, or is set to C<undef> when the algorithm MUST
be invoked without no manifest URI.

=head1 ERROR REPORTS

@@ TBW

The list of the error types is available in
Whatpm Error Types <http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.

=head1 TO DO

Documentation for parse_byte_string.

Tokenizer should emit a sequence of character tokens as one token
to improve performance.

A method that accepts a byte stream as an input.

Charset detection algorithm.

Documentation for the setter of inner_html.

And there are many "TODO"s and "ISSUE"s in the source code.

=head1 DEPENDENCY

This module requires L<Error>.  That module is available at CPAN
<http://search.cpan.org/author/SHLOMIF/Error-0.17009/lib/Error.pm>.
It is also part of manakai-core distribution
<http://suika.fam.cx/www/2006/manakai/>.

=head1 SEE ALSO

Whatpm <http://suika.fam.cx/www/markup/html/whatpm/readme>.

Whatpm Error Types
<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.

HTML5 <http://whatwg.org/html5>.

L<Whatpm::HTML::Serializer>.

L<Whatpm::NanoDOM>.

L<Whatpm::ContentChecker::HTML>.

=head1 AUTHOR

Wakaba <w@suika.fam.cx>.

=head1 LICENSE

Copyright 2007 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: 2007/11/11 04:59:36 $
1	wakaba	1.1	=head1 NAME
2
3	wakaba	1.6	Whatpm::HTML - An HTML Parser and Serializer
4	wakaba	1.1
5			=head1 SYNOPSIS
6
7	wakaba	1.2	use Whatpm::HTML;
8	wakaba	1.1
9			my $s = q<<!DOCTYPE html><html>...</html>>;
10			# $doc = an empty DOM \|Document\| object
11			my $on_error = sub {
12	wakaba	1.6	my %error = @_;
13			warn $error{type}, "\n";
14	wakaba	1.1	};
15
16	wakaba	1.8	Whatpm::HTML->parse_char_string ($s => $doc, $onerror);
17	wakaba	1.1
18	wakaba	1.6	## Now, \|$doc\| is the DOM representation of \|$s\|.
19	wakaba	1.1
20			=head1 DESCRIPTION
21
22	wakaba	1.2	The C<Whatpm::HTML> module contains HTML parser and serializer.
23	wakaba	1.1
24			The HTML parser can be used to construct the DOM tree representation
25			from an HTML document. The parsing and tree construction are done
26			as described in the Web Application 1.0 specification.
27
28			The HTML serializer can be used to obtain the HTML document representation
29			of a DOM tree (or a tree fragment thereof). The serialization
30			is performed as described in the Web Applications 1.0 specification
31			for C<innerHTML> DOM attribute.
32
33	wakaba	1.2	This module is part of Whatpm - Perl Modules for
34	wakaba	1.1	Web Hypertext Application Technologies.
35
36			=head1 METHODS
37
38			=over 4
39
40	wakaba	1.8	=item [I<$doc> =] Whatpm::HTML->parse_char_string (I<$s>, I<$doc>[, I<$onerror>]);
41	wakaba	1.1
42			Parse a string I<$s> as an HTML document.
43
44			The first argument, I<$s>, MUST be a string. It is parsed
45			as a sequence of characters representing an HTML document.
46
47			The second argument, I<$doc>, MUST be an empty read-write
48			DOM C<Document> object. The HTML DOM tree is constructed
49			onto this C<Document> object.
50
51			The third argument, I<$onerror>, MUST be a reference to
52			the error handler code. Whenever a parse error is detected,
53			this code is invoked with an argument that contains a
54			useless string that might describe what is wrong.
55			The code MAY throw an exception, so that whole the parsing
56			process aborts. Otherwise, the parser will continue to
57			process the input. The code MUST NOT modify I<$s> or I<$doc>.
58			If it does, then the result is undefined.
59			This argument is optional; if missing, any
60			parse error makes that string being C<warn>ed.
61
62	wakaba	1.3	B<NOTE>: To be a conforming user agent, the code MUST either
63			abort the processing by throwing an exception at the first
64			invocation or MUST continue the processing until the parser
65			stops.
66
67	wakaba	1.1	The method returns the DOM C<Document> object (i.e. the second argument).
68
69	wakaba	1.2	Note that the C<Whatpm::NanoDOM> module provides a non-conforming
70	wakaba	1.4	implementation of DOM that only implements a subset that
71	wakaba	1.2	is necessary for the purpose of C<Whatpm::HTML>'s parsing and
72	wakaba	1.1	serializing.
73			With this module, creating a new HTML C<Document> object
74	wakaba	1.3	from a string containing HTML document might be coded as:
75	wakaba	1.1
76	wakaba	1.2	use Whatpm::HTML;
77			use Whatpm::NanoDOM;
78	wakaba	1.8	my $doc = Whatpm::HTML->parse_char_string
79	wakaba	1.2	($s => Whatpm::NanoDOM::Document->new, $onerror);
80	wakaba	1.1
81			=back
82
83	wakaba	1.5	=head1 LOW-LEVEL INTERFACE
84
85			@@ TBW
86
87			=head2 Application Cache Selection Algorithm Hook
88
89			Once a parser I<$p> is instantiated by method C<new>,
90	wakaba	1.6	a C<CODE> reference can be set to C<< I<$p>->{application_cache_selection} >>.
91	wakaba	1.5	That C<CODE> will be called back when the application cache selection
92			algorithm MUST be run per HTML5. By default,
93	wakaba	1.6	C<< I<$p>->{application_cache_selection} >> is set to an empty subroutine.
94
95			The subroutine will be invoked with an argument I<manifest_uri>,
96			which is set to the manifest URI when the algorithm MUST be invoked
97			with a manifest URI, or is set to C<undef> when the algorithm MUST
98			be invoked without no manifest URI.
99
100			=head1 ERROR REPORTS
101
102			@@ TBW
103
104			The list of the error types is available in
105			Whatpm Error Types <http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.
106	wakaba	1.5
107	wakaba	1.1	=head1 TO DO
108
109	wakaba	1.8	Documentation for parse_byte_string.
110
111	wakaba	1.1	Tokenizer should emit a sequence of character tokens as one token
112			to improve performance.
113
114			A method that accepts a byte stream as an input.
115
116			Charset detection algorithm.
117
118	wakaba	1.4	Documentation for the setter of inner_html.
119	wakaba	1.1
120			And there are many "TODO"s and "ISSUE"s in the source code.
121
122	wakaba	1.8	=head1 DEPENDENCY
123
124			This module requires L<Error>. That module is available at CPAN
125			<http://search.cpan.org/author/SHLOMIF/Error-0.17009/lib/Error.pm>.
126			It is also part of manakai-core distribution
127			<http://suika.fam.cx/www/2006/manakai/>.
128
129	wakaba	1.1	=head1 SEE ALSO
130
131	wakaba	1.6	Whatpm <http://suika.fam.cx/www/markup/html/whatpm/readme>.
132
133			Whatpm Error Types
134			<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.
135
136			HTML5 <http://whatwg.org/html5>.
137	wakaba	1.3
138	wakaba	1.7	L<Whatpm::HTML::Serializer>.
139
140	wakaba	1.6	L<Whatpm::NanoDOM>.
141	wakaba	1.1
142	wakaba	1.6	L<Whatpm::ContentChecker::HTML>.
143	wakaba	1.1
144			=head1 AUTHOR
145
146			Wakaba <w@suika.fam.cx>.
147
148			=head1 LICENSE
149
150			Copyright 2007 Wakaba <w@suika.fam.cx>
151
152			This library is free software; you can redistribute it
153			and/or modify it under the same terms as Perl itself.
154
155			=cut
156
157	wakaba	1.8	# $Date: 2007/11/11 04:59:36 $