SAX(3)

NAME
XML::SAX - Simple API for XML

SYNOPSIS
  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();

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

USING A SAX2 PARSER
The factory class is XML::SAX::ParserFactory. Please see the documentation of that module for how to instantiate a SAX parser: the XML::SAX::ParserFactory manpage. 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 SAX2 parser (defaulting to XML::SAX::PurePerl if no others are found) and return it to you.

In order to learn how to use SAX to parse XML, you will need to read the XML::SAX::Intro manpage and for reference, the XML::SAX::Specification manpage.

WRITING A SAX2 PARSER
The first thing to remember in writing a SAX2 parser is to subclass XML::SAX::Base. This will make your life infinitely easier, by providing a number of methods automagically for you. See the XML::SAX::Base manpage for more details.

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

The best way to do this is to follow these rules:
  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.
  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 - \$(NAME) 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 \$(NAME) in the above. 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});
  };

EXPORTS
By default, XML::SAX exports nothing into the caller's namespace. However you can request the symbols `Namespaces' and `Validation' 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();

AUTHOR
Matt Sergeant, matt@sergeant.org

Kip Hampton, khampton@totalcinema.com

Robin Berjon, robin@knowscape.com

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

SEE ALSO
the XML::SAX::Base manpage for writing SAX Filters and Parsers

the XML::SAX::PurePerl manpage for an XML parser written in 100% pure perl.

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