5.7.1. XML::SAX::ParserFactory

We start with the parser selection interface, XML::SAX::ParserFactory. For those of you who have used DBI, this class is very similar. It's a front end to all the SAX parsers on your system. You simply request a new parser from the factory and it will dig one up for you. Let's say you want to use any SAX parser with your handler package XML::SAX::MyHandler.

Here's how to fetch the parser and use it to read a file:

use XML::SAX::ParserFactory;
use XML::SAX::MyHandler;
my $handler = new XML::SAX::MyHandler;
my $parser = XML::SAX::ParserFactory->parser( Handler => $handler );
$parser->parse_uri( "foo.xml" );

The parser you get depends on the order in which you've installed the modules. The last one (with all the available features specified with RequiredFeatures, if any) will be returned by default. But maybe you don't want that one. No problem; XML::SAX maintains a registry of SAX parsers that you can choose from. Every time you install a new SAX parser, it registers itself so you can call upon it with ParserFactory. If you know you have the XML::SAX::BobsParser parser installed, you can require an instance of it by setting the variable $XML::SAX::ParserPackage as follows:

use XML::SAX::ParserFactory;
use XML::SAX::MyHandler;
my $handler = new XML::SAX::MyHandler;
$XML::SAX::ParserPackage = "XML::SAX::BobsParser( 1.24 )";
my $parser = XML::SAX::ParserFactory->parser( Handler => $handler );

To see a list of all the parsers available to XML::SAX, call the parsers( ) method:

use XML::SAX;

my @parsers = @{XML::SAX->parsers( )};

foreach my $p ( @parsers ) {
    print "\n", $p->{ Name }, "\n";
    foreach my $f ( sort keys %{$p->{ Features }} ) {
        print "$f => ", $p->{ Features }->{ $f }, "\n";
    }
}

It returns a reference to a list of hashes, with each hash containing information about a parser, including the name and a hash of features. When we ran the program above we were told that XML::SAX had two registered parsers, each supporting namespaces:

XML::LibXML::SAX::Parser
http://xml.org/sax/features/namespaces => 1

XML::SAX::PurePerl
http://xml.org/sax/features/namespaces => 1

5.7.2. SAX2 Handler Interface

One important new facet to this class of parsers is that they recognize namespaces. This recognition is one of the innovations of SAX2. Previously, SAX parsers treated a qualified name as a single unit: a combined namespace prefix and local name. Now you can tease out the namespaces, see where their scope begins and ends, and do more than you could before.

5.7.3. SAX2 Parser Interface

$parser->parse( Handler => $handler, 
                 Source => { SystemId => "data.xml" });

The Handler property sets a generic set of handlers that will be used by default. However, each class of handlers has its own assignment slot that will be checked before Handler. These settings include: ContentHandler, DTDHandler, EntityResolver, and ErrorHandler. All of these settings are optional. If you don't assign a handler, the parser will silently ignore events and handle errors in its own way.

CharacterStream

This kind of filehandle works in Perl Version 5.7.2 and higher using PerlIO. No encoding translation should be necessary. Use the read( ) function to get a number of characters from it, or use sysread( ) to get a number of bytes. If the CharacterStream property is set, the parser ignores ByteStream or SystemId.

ByteStream

This property sets a byte stream to be read. If CharacterStream is set, this property is ignored. However, it supersedes SystemId. The Encoding property should be set along with this property.

PublicId

This property is optional, but if the application submits a public identifier, it is stored here.

SystemId

This string represents a system-specific location for a document, such as a URI or filesystem path. Even if the source is a character stream or byte stream, this parameter is still useful because it can be used as an offset for external entity references.

Encoding

The character encoding, if known, is stored here.

Any other options you want to set are in the set of features defined for SAX2. For example, you can tell a parser that you are interested in special treatment for namespaces. One way to set features is by defining the Features property in the options hash given to the parse( ) method. Another way is with the method set_feature( ). For example, here's how you would turn on validation in a validating parser using both methods:

$parser->parse( Features => { 'http://xml.org/sax/properties/validate' => 1 } );
$parser->set_feature( 'http://xml.org/sax/properties/validate', 1 );

5.7.4. Example: A Driver

Making your own SAX parser is simple, as most of the work is handled by a base class, XML::SAX::Base. All you have to do is create a subclass of this object and override anything that isn't taken care of by default. Not only is it convenient to do this, but it will result in code that is much safer and more reliable than if you tried to create it from scratch. For example, checking if the handler package implements the handler you want to call is done for you automatically.

Since web logs are line oriented (one entry per line), it makes sense to create a subroutine that handles a single line, _process_line( ). All it has to do is break down the web log entry into component parts and package them in XML elements. The parse( ) routine simply chops the document into separate lines and feeds them into the line processor one at a time.

Notice that we don't call event handlers in the handler package directly. Rather, we pass the data through routines in the base class, using it as an abstract layer between the parser and the handler. This is convenient for you, the parser developer, because you don't have to check if the handler package is listening for that type of event. Again, the base class is looking out for us, making our lives easier.

We use XML::SAX::ParserFactory to demonstrate how a parser can be selected once it is registered. If you wish, you can define attributes for the parser so that subsequent queries can select it based on those properties rather than its name.

5.7.5. Installing Your Own Parser

First, we start a new project with the following command:

h2xs -AX -n LogDriver

LogDriver.pm, the module to be installed, doesn't need much extra code to make h2xs happy. It only needs a variable, $VERSION, since h2xs is (justifiably) finicky about that information.

As you know from installing CPAN modules, the first thing you do when opening an installer archive is run the command perl Makefile.PM. Running this command generates a file called Makefile, which configures the installer to your system. Then you can run make and make install to load the module in the right place.

Any deviation from the default behavior of the installer must be coded in the Makefile.PM program. Untouched, it looks like this:

use ExtUtils::MakeMaker;
WriteMakefile(
    'NAME'                => 'LogDriver',         # module name
    'VERSION_FROM'        => 'LogDriver.pm',      # finds version
 );

'PREREQ_PM' => { 'XML::SAX' => 0 }

Adding this line triggers a check during installation to see if XML::SAX exists on the system. If not, the installation aborts with an error message. We don't want to install our parser until there is a framework to accept it.

This subroutine should also be added to Makefile.PM:

sub MY::install {
    package MY;
    my $script = shift->SUPER::install(@_);
    $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;
}