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 <[email protected]>

=head1 LICENSE

Copyright 2007-2008 Wakaba <[email protected]>

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	wakaba	1.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	wakaba	1.2	=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	wakaba	1.1	=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 <[email protected]>
144
145			=head1 LICENSE
146
147	wakaba	1.2	Copyright 2007-2008 Wakaba <[email protected]>
148	wakaba	1.1
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	wakaba	1.2	# $Date: 2007/08/06 10:56:50 $