whatpm/Whatpm/ContentChecker.pod

=head1 NAME

Whatpm::ContentChecker - DOM Conformance Checker

=head1 SYNOPSIS

  use Whatpm::ContentChecker;
  
  Whatpm::ContentChecker->check_document ($doc, sub {
    my %arg = @_;
    warn get_node_path ($arg{node}), ": ",
        ($arg{level} || "Error"), ": ",
        $arg{type}, "\n";
  });
  
  Whatpm::ContentChecker->check_element ($doc, sub {
    my %arg = @_;
    warn get_node_path ($arg{node}), ": ",
        ($arg{level} || "Error"), ": ",
        $arg{type}, "\n";
  });

=head1 DESCRIPTION

The C<Whatpm::ContentChecker> Perl module contains two methods
to validate DOM tree for its conformance to the markup language
in use.

This module is part of Whatpm, Perl Modules for
Web Hypertext Application Technologies, which is a subproject
of manakai.

=head1 METHODS

This module contains two static methods:

=over 4

=item Whatpm::ContentChecker->check_document (I<$document>, I<$onerror>);

Checks a document, I<$document>, and its descendant for their
conformance.  If there is an error or a warnign, then the
I<$onerror> C<CODE> is invoked with named arguments same
as ones for the method C<check_element>.

=item Whatpm::ContentChecker->check_element (I<$element>, I<$onerror>);

Checks an element, I<$element>, and its descendant for their conformance.
If there is an error or a warning, then the I<$onerror> C<CODE>
is invoked with named arguments:

=over 4

=item level (Might be C<undef>)

A string which describes the severity of the error or warning.
For the list of the severities, see
<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.

=item node (Always specified)

The node with which the error is detected.

=item type (Always specified)

A string which describes the type of the error or warning.
For the list of the errors and warnings, see
<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.

=back

=back

=head1 BUGS

This conformance checker is work in progress; it I<might> not be
able to detect all the errors in the DOM tree, and it I<might> 
detect an error for a node that is conforming in fact.

=head1 NOTES ON IMPLEMENTATION DETAILS

I<This section is not complete.>

This section describes various internal constructions used in
L<Whatpm::ContentChecker> and relevant modules.  These data structures
are not public interfaces -- they should not be accessed or modified
by applications.  They are documented here for the convenience of
development only.

=head2 The C<< $self->{flag} >> Structure

=over 4

=item C<< $self->{flag}->{has_label} >>

This flag is set to a true value if and only if there is a C<label>
element ancestor of the current node.

=item C<< $self->{flag}->{has_labelable} >>

This flag is set to C<1> if and only if a nearest ancestor C<label>
element has the C<for> attribute and there is no labelable
form-associated element that is a descendant of the C<label> element
and precedes the current node in tree order.  This flag is set to C<2>
if and only if there is a labelable form-associated element that is a
descendant of the nearest ancestor C<label> element of the current
node and precedes the current node in tree order.  This flag is
otherwise set to a false value.  B<However>, when there is no ancestor
C<label> element of the current node, i.e. when 
C<< $self->{flag}->{has_label} >> is false, the value of the
C<< $self->{flag}->{has_labelable} >> flag is I<undefined>.

=back

=head2 The C<$element_state> Structure

=over 4

=item C<< $element_state->{has_label_original} >>

Used to preserve the value of C<< $self->{flag}->{has_label} >> at the
time of invocation of the method C<element_start> for the element
being checked.

=item C<< $element_state->{has_labelable_original} >>

Used to preserve the value of C<< $self->{flag}->{has_labelable} >> at
the time of invocation of the method C<element_start> for the element
being checked.

=back

=head1 SEE ALSO

L<Whatpm::ContentChecker::Atom>

L<Whatpm::ContentChecker::HTML>

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

=head1 AUTHOR

Wakaba <w@suika.fam.cx>

=head1 LICENSE

Copyright 2007-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: 2007/08/06 10:56:50 $
1	=head1 NAME
2
3	Whatpm::ContentChecker - DOM Conformance Checker
4
5	=head1 SYNOPSIS
6
7	use Whatpm::ContentChecker;
8
9	Whatpm::ContentChecker->check_document ($doc, sub {
10	my %arg = @_;
11	warn get_node_path ($arg{node}), ": ",
12	($arg{level} \|\| "Error"), ": ",
13	$arg{type}, "\n";
14	});
15
16	Whatpm::ContentChecker->check_element ($doc, sub {
17	my %arg = @_;
18	warn get_node_path ($arg{node}), ": ",
19	($arg{level} \|\| "Error"), ": ",
20	$arg{type}, "\n";
21	});
22
23	=head1 DESCRIPTION
24
25	The C<Whatpm::ContentChecker> Perl module contains two methods
26	to validate DOM tree for its conformance to the markup language
27	in use.
28
29	This module is part of Whatpm, Perl Modules for
30	Web Hypertext Application Technologies, which is a subproject
31	of manakai.
32
33	=head1 METHODS
34
35	This module contains two static methods:
36
37	=over 4
38
39	=item Whatpm::ContentChecker->check_document (I<$document>, I<$onerror>);
40
41	Checks a document, I<$document>, and its descendant for their
42	conformance. If there is an error or a warnign, then the
43	I<$onerror> C<CODE> is invoked with named arguments same
44	as ones for the method C<check_element>.
45
46	=item Whatpm::ContentChecker->check_element (I<$element>, I<$onerror>);
47
48	Checks an element, I<$element>, and its descendant for their conformance.
49	If there is an error or a warning, then the I<$onerror> C<CODE>
50	is invoked with named arguments:
51
52	=over 4
53
54	=item level (Might be C<undef>)
55
56	A string which describes the severity of the error or warning.
57	For the list of the severities, see
58	<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.
59
60	=item node (Always specified)
61
62	The node with which the error is detected.
63
64	=item type (Always specified)
65
66	A string which describes the type of the error or warning.
67	For the list of the errors and warnings, see
68	<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>.
69
70	=back
71
72	=back
73
74	=head1 BUGS
75
76	This conformance checker is work in progress; it I<might> not be
77	able to detect all the errors in the DOM tree, and it I<might>
78	detect an error for a node that is conforming in fact.
79
80	=head1 NOTES ON IMPLEMENTATION DETAILS
81
82	I<This section is not complete.>
83
84	This section describes various internal constructions used in
85	L<Whatpm::ContentChecker> and relevant modules. These data structures
86	are not public interfaces -- they should not be accessed or modified
87	by applications. They are documented here for the convenience of
88	development only.
89
90	=head2 The C<< $self->{flag} >> Structure
91
92	=over 4
93
94	=item C<< $self->{flag}->{has_label} >>
95
96	This flag is set to a true value if and only if there is a C<label>
97	element ancestor of the current node.
98
99	=item C<< $self->{flag}->{has_labelable} >>
100
101	This flag is set to C<1> if and only if a nearest ancestor C<label>
102	element has the C<for> attribute and there is no labelable
103	form-associated element that is a descendant of the C<label> element
104	and precedes the current node in tree order. This flag is set to C<2>
105	if and only if there is a labelable form-associated element that is a
106	descendant of the nearest ancestor C<label> element of the current
107	node and precedes the current node in tree order. This flag is
108	otherwise set to a false value. B<However>, when there is no ancestor
109	C<label> element of the current node, i.e. when
110	C<< $self->{flag}->{has_label} >> is false, the value of the
111	C<< $self->{flag}->{has_labelable} >> flag is I<undefined>.
112
113	=back
114
115	=head2 The C<$element_state> Structure
116
117	=over 4
118
119	=item C<< $element_state->{has_label_original} >>
120
121	Used to preserve the value of C<< $self->{flag}->{has_label} >> at the
122	time of invocation of the method C<element_start> for the element
123	being checked.
124
125	=item C<< $element_state->{has_labelable_original} >>
126
127	Used to preserve the value of C<< $self->{flag}->{has_labelable} >> at
128	the time of invocation of the method C<element_start> for the element
129	being checked.
130
131	=back
132
133	=head1 SEE ALSO
134
135	L<Whatpm::ContentChecker::Atom>
136
137	L<Whatpm::ContentChecker::HTML>
138
139	<http://suika.fam.cx/gate/2005/sw/Whatpm%20Error%20Types>
140
141	=head1 AUTHOR
142
143	Wakaba <w@suika.fam.cx>
144
145	=head1 LICENSE
146
147	Copyright 2007-2008 Wakaba <w@suika.fam.cx>
148
149	This library is free software; you can redistribute it
150	and/or modify it under the same terms as Perl itself.
151
152	=cut
153
154	# $Date: 2007/08/06 10:56:50 $