XML::SAX (3pm)

  use XML::SAX;

  # get a list of known parsers
  my $parsers = XML::SAX->parsers();

  # add/update a parser
  XML::SAX->add_parser(q(XML::SAX::PurePerl));

  # remove parser
  XML::SAX->remove_parser(q(XML::SAX::Foodelberry));

  # save parsers
  XML::SAX->save_parsers();

\s-1XML::SAX\s0 is a \s-1SAX\s0 parser access \s-1API\s0 for Perl. It includes classes and APIs required for implementing \s-1SAX\s0 drivers, along with a factory class for returning any \s-1SAX\s0 parser installed on the user's system.

The factory class is XML::SAX::ParserFactory. Please see the documentation of that module for how to instantiate a \s-1SAX\s0 parser: XML::SAX::ParserFactory. However if you don't want to load up another manual page, here's a short synopsis:

use XML::SAX::ParserFactory; use XML::SAX::XYZHandler; my $handler = XML::SAX::XYZHandler->new(); my $p = XML::SAX::ParserFactory->parser(Handler => $handler); $p->parse_uri("foo.xml"); # or $p->parse_string("<foo/>") or $p->parse_file($fh);

This will automatically load a \s-1SAX2\s0 parser (defaulting to XML::SAX::PurePerl if no others are found) and return it to you.

In order to learn how to use \s-1SAX\s0 to parse \s-1XML\s0, you will need to read XML::SAX::Intro and for reference, XML::SAX::Specification.

The first thing to remember in writing a \s-1SAX2\s0 parser is to subclass XML::SAX::Base. This will make your life infinitely easier, by providing a number of methods automagically for you. See XML::SAX::Base for more details.

When writing a \s-1SAX2\s0 parser that is compatible with \s-1XML::SAX\s0, you need to inform \s-1XML::SAX\s0 of the presence of that driver when you install it. In order to do that, \s-1XML::SAX\s0 contains methods for saving the fact that the parser exists on your system to a \*(L"\s-1INI\s0\*(R" file, which is then loaded to determine which parsers are installed.

The best way to do this is to follow these rules:

• Add \s-1XML::SAX\s0 as a prerequisite in Makefile.PL: WriteMakefile( ... PREREQ_PM => { 'XML::SAX' => 0 }, ... ); Alternatively you may wish to check for it in other ways that will cause more than just a warning.

• Add the following code snippet to your Makefile.PL: sub MY::install { package MY; my $script = shift->SUPER::install(@_); if (ExtUtils::MakeMaker::prompt( "Do you want to modify ParserDetails.ini?", 'Y') =~ /^y/i) { $script =~ s/install :: (.*)$/install :: $1 install_sax_driver/m; $script .= <<"INSTALL";

  install_sax_driver : \t\@\$(PERL) -MXML::SAX -e "XML::SAX->add_parser(q(\$(NAME)))->save_parsers()"

  INSTALL } return $script; } Note that you should check the output of this - \$(\s-1NAME\s0) will use the name of your distribution, which may not be exactly what you want. For example XML::LibXML has a driver called XML::LibXML::SAX::Generator, which is used in place of \$(\s-1NAME\s0) in the above.

• Add an \s-1XML::SAX\s0 test: A test file should be added to your t/ directory containing something like the following: use Test; BEGIN { plan tests => 3 } use XML::SAX; use XML::SAX::PurePerl::DebugHandler; XML::SAX->add_parser(q(XML::SAX::MyDriver)); local $XML::SAX::ParserPackage = 'XML::SAX::MyDriver'; eval { my $handler = XML::SAX::PurePerl::DebugHandler->new(); ok($handler); my $parser = XML::SAX::ParserFactory->parser(Handler => $handler); ok($parser); ok($parser->isa('XML::SAX::MyDriver'); $parser->parse_string("<tag/>"); ok($handler->{seen}{start_element}); };

By default, \s-1XML::SAX\s0 exports nothing into the caller's namespace. However you can request the symbols \*(C`Namespaces\*(C' and \*(C`Validation\*(C' which are the URIs for those features, allowing an easier way to request those features via ParserFactory:

use XML::SAX qw(Namespaces Validation); my $factory = XML::SAX::ParserFactory->new(); $factory->require_feature(Namespaces); $factory->require_feature(Validation); my $parser = $factory->parser();

Current maintainer: Grant McLean, [email protected]

Originally written by:

Matt Sergeant, [email protected]

Kip Hampton, [email protected]

Robin Berjon, [email protected]

This is free software, you may use it and distribute it under the same terms as Perl itself.

XML::SAX::Base for writing \s-1SAX\s0 Filters and Parsers

XML::SAX::PurePerl for an \s-1XML\s0 parser written in 100% pure perl.

XML::SAX::Exception for details on exception handling