#
# Use XML::DOM::ValParser instead of XML::DOM::Parser and it will
# use XML::Checker to validate XML at parse time.
#

package XML::DOM::ValParser;

use strict;
use XML::DOM;
use XML::Checker::Parser;

use vars qw( @ISA @SupportedHandlers );

@ISA = qw( XML::Checker::Parser );

# These XML::Parser handlers are currently supported by XML::DOM
@SupportedHandlers = qw( Init Final Char Start End Default Doctype
			 CdataStart CdataEnd XMLDecl Entity Notation Proc 
			 Default Comment Attlist Element Unparsed );

sub new
{
    my ($class, %args) = @_;
    
    my %handlers = ();
    for (@SupportedHandlers)
    {
	my $domHandler = "XML::Parser::Dom::$_";
	$handlers{$_} = \&$domHandler;
    }
    $args{Handlers} = \%handlers;
    $class->SUPER::new (%args);
}

sub parse
{
    # Do what XML::DOM::Parser normally does.
    # Temporarily override his @ISA, so that he thinks he's a
    # XML::DOM::ValParser and calls the right SUPER::parse(),
    # (otherwise he thinks he's an XML::DOM::Parser and you see runtime
    #  error: Can't call method "Init" on unblessed reference ...)
    local @XML::DOM::Parser::ISA = @ISA;
    local $XML::Checker::Parser::_skipInsignifWS = $_[0]->{SkipInsignifWS};
    XML::DOM::Parser::parse (@_);
}

1; # package return code

__END__

=head1 NAME

XML::DOM::ValParser - an XML::DOM::Parser that validates at parse time

=head1 SYNOPSIS

 use XML::DOM::ValParser;

 my %expat_options = (KeepCDATA => 1, 
		      Handlers => [ Unparsed => \&my_Unparsed_handler ]);
 my $parser = new XML::DOM::ValParser (%expat_options);

 eval {
     local $XML::Checker::FAIL = \&my_fail;
     my $doc = $parser->parsefile ("fail.xml");
     ... XML::DOM::Document was created sucessfully ...
 };
 if ($@) {
     # Either XML::Parser (expat) threw an exception or my_fail() died.
     ... your error handling code here ...
     # Note that the XML::DOM::Document is automatically disposed off and
     # will be garbage collected
 }

 # Throws an exception (with die) when an error is encountered, this
 # will stop the parsing process.
 # Don't die if a warning or info message is encountered, just print a message.
 sub my_fail {
     my $code = shift;
     die XML::Checker::error_string ($code, @_) if $code < 200;
     XML::Checker::print_error ($code, @_);
 }

=head1 DESCRIPTION

Use XML::DOM::ValParser wherever you would use L<XML::DOM::Parser> and
your XML will be checked using L<XML::Checker> at parse time.

See L<XML::DOM> for details on XML::DOM::Parser options.
See L<XML::Checker> for details on setting the fail handler (my_fail.)

The following handlers are currently supported, just like XML::DOM::Parser:
Init, Final, Char, Start, End, Default, Doctype, CdataStart, CdataEnd, 
XMLDecl, Entity, Notation, Proc, Default, Comment, Attlist, Element, Unparsed.

=head1 XML::DOM::ValParser

XML::DOM::ValParser extends from L<XML::Checker::Parser>. It creates an
L<XML::Checker> object and routes all event handlers through the checker,
before processing the events to create the XML::DOM::Document.

Just like L<XML::Checker::Parser>, the checker object can be retrieved with
the getChecker() method and can be reused later on (provided that the DOCTYPE
section of the XML::DOM::Document did not change in the mean time.)

You can control which errors are fatal (and therefore should stop creation
of the XML::DOM::Document) by filtering the appropriate error codes in
the global $XML::Checker::FAIL handler 
(see L<XML::Checker/ERROR_HANDLING>) and 
calling I<die> or I<croak> appropriately.

Just like XML::Checker::Parser, XML::DOM::ValParser supports the 
SkipExternalDTD and SkipInsignifWS options. See L<XML::Checker::Parser>
for details.

=head1 AUTHOR

Send bug reports, hints, tips, suggestions to Enno Derksen at
<F<enno@att.com>>.

=head1 SEE ALSO

L<XML::DOM>, L<XML::Checker> (L<XML::Checker/SEE_ALSO>)