XML Reference Guide

Rather than treating an XML document as a tree-like structure, the Simple API for XML, or SAX, treats it as a series of events such as startDocument or endElement.

Creating a SAX application involves processing events as they arrive, keeping in mind that at any given moment, the application knows only about the current event; if you need information about previous events, you need to save it yourself. For example, consider the order.xml file:

<?xml version="1.0"?>
<order orderid="THX1138" customerNumber="3263827">
    <lineitem itemid="C33">
       <item>3/4" Hex Bolt</item>
       <quantity>36</quantity>
       <unitprice currency="dollars">.35</unitprice>
    </lineitem>
    <lineitem itemid="M48">
       <item>Condenser</item>
       <quantity>1</quantity>
       <unitprice currency="dollars">2200</unitprice>
    </lineitem>
    <delivery>Overnight</delivery>
</order>

In order to create a Perl application that displays the content of the file, we would need to first create the parser and use it to parse the file:

package MyContentHandler;

use XML::SAX;
use base qw(XML::SAX::Base);

XML::SAX->add_parser(q(XML::SAX::PurePerl));

my $factory = XML::SAX::ParserFactory->new();
my $parser = $factory->parser( Handler => MyContentHandler->new() );

eval { $parser->parse_uri('order.xml'); };

print "Error parsing file: $@" if $@;

Starting at the top, we're declaring this code to be part of a package, which will give us the opportunity to reference it as a class. Next, we're making the XML::SAX and XML::SAX::Base packages available. (You can install these from CPAN.) Next, we're making the XML::SAX::PurePerl parser, part of the XML::SAX package, available. (Depending on your installation, you may be able to skip this step.)

Next, create the ParserFactory, and then the parser itself. Notice that when we create the parser, we're also providing a reference for the Handler, which will handle the actual events when the parser parses the file.

Finally, we're parsing the file and outputting any errors that were encountered.

Now, if you run this script, you'll notice that nothing happens. Or at least, nothing seems to happen. The various methods, such as start_element, are executed, but the default implementation is to do nothing with them. To change that, we can override those methods here in the script, like so:

package MyContentHandler;

use base qw(XML::SAX::Base);

sub start_document {
   print "Document START\n";
}

sub end_document {
   print "Document END\n";
}

sub start_element{
   my $self = shift;
   my $el = shift;

   $self->display_text();

   print "Element START: \n";
   print "Namespace = $el->{NamespaceURI}\n";
   print "LocalName= $el->{LocalName}\n";

   foreach my $ak (keys %{ $el->{Attributes} } ) {
      my $at = $el->{Attributes}->{$ak};
      print qq(Attribute $at->{Name} = "$at->{Value}"\n);
   }
   print "***************n";
}

sub end_element{
   my $self = shift;
   my $el = shift;

   print "Element END: \n";
   print "Namespace = $el->{NamespaceURI}\n";
   print "LocalName= $el->{LocalName}\n";

   print "***************n";
}

use XML::SAX;

XML::SAX->add_parser(q(XML::SAX::PurePerl));

my $factory = XML::SAX::ParserFactory->new();
my $parser = $factory->parser( Handler => MyContentHandler->new() );

eval { $parser->parse_uri('order.xml'); };

print "Error parsing file: $@" if $@;

The first two subroutines are easy. When the parser starts parsing the document, the start_document event fires, and which causes the script to execute the start_document() method. When it finishes the file, the end_document() method executes.

For each element, it's a little more complicated. The start_element() and end_element() methods execute when you'd expect them to (that is, with their corresponding events) but in this case they also serve additional functions. In each case, _@ represents the arguments passed to the method, so first we're retrieving a reference to the overall class. We can then retrieve the actual element object itself.

In the case of the start_element() method, the element is represented by a hash that includes information on the namespace, the local name of the element, and other information, including the attributes. The attributes are themselves a hash, with the name and value accessible.

If we run the script, we get the following output:

Document START
Element START:
Namespace=
LocalName= order
Attribute customerNumber = "3263827"
Attribute orderid = "THX1138"
***************
Element START:
Namespace=
LocalName= lineitem
Attribute itemid = "C33"
***************
Element START:
Namespace=
LocalName= item
***************
Element END:
Namespace=
LocalName= item
***************
Element START:
Namespace=
LocalName= quantity
***************
Element END:
Namespace=
LocalName= quantity
***************
Element START:
Namespace=
LocalName= unitprice
Attribute currency = "dollars"
***************
Element END:
Namespace=
LocalName= unitprice
***************
Element END:
Namespace=
LocalName= lineitem
***************
Element START:
Namespace=
LocalName= lineitem
Attribute itemid = "M48"
***************
Element START:
Namespace=
LocalName= item
***************
Element END:
Namespace=
LocalName= item
***************
Element START:
Namespace=
LocalName= quantity
***************
Element END:
Namespace=
LocalName= quantity
***************
Element START:
Namespace=
LocalName= unitprice
Attribute currency = "dollars"
***************
Element END:
Namespace=
LocalName= unitprice
***************
Element END:
Namespace=
LocalName= lineitem
***************
Element START:
Namespace=
LocalName= delivery
***************
Element END:
Namespace=
LocalName= delivery
***************
Element END:
Namespace=
LocalName= order
***************
Document END

So far we've looked at the elements, but not to their content. The text children of an element are fed as characters, but there's no guaranteeing that you'll get all of them in one event. For example, the item name "Condenser" could be supplied in a single event, or it could come as a series of events, where one or more characters are fed to the characters() method. To solve that problem, we can save the current text as part of the object, and then display and clear it as necessary:

package MyContentHandler;

use base qw(XML::SAX::Base);

sub start_document {
  print "Document START\n";
  my $self = shift;
  $self->{text} = '';
}

sub end_document {
   print "Document END\n";
}

sub start_element{
   my $self = shift;
   my $el = shift;

   $self->display_text();

   print "Element START: \n";
   print "Namespace= $el->{NamespaceURI}\n";
   print "LocalName= $el->{LocalName}\n";

   foreach my $ak (keys %{ $el->{Attributes} } ) {
      my $at = $el->{Attributes}->{$ak};
      print qq(Attribute $at->{Name} = "$at->{Value}"\n);
   }
   print "***************\n";
}

sub end_element{
   my $self = shift;
   my $el = shift;

   $self->display_text();

   print "Element END: \n";
   print "Namespace= $el->{NamespaceURI}\n";
   print "LocalName= $el->{LocalName}\n";

   print "***************\n";
}

sub display_text {
   my $self = shift;
   if ( defined( $self->{text} )
        && $self->{text} ne "" ) {
      print " text: [$self->{text}]\n";
      $self->{text} = '';
   }
}

sub characters {
    my $self = shift;
    my $text = shift;

    $self->{text} .= $text->{Data};
}


use XML::SAX;

XML::SAX->add_parser(q(XML::SAX::PurePerl));

my $factory = XML::SAX::ParserFactory->new();
my $parser = $factory->parser( Handler => MyContentHandler->new() );

eval { $parser->parse_uri('order.xml'); };

print "Error parsing file: $@" if $@;

The issue of text illustrates the point I made earlier about having to save information explicitly if it needs to be available across events, but it's not the only reason. For example, consider this version of the script, which lists the order information, including the extended total for each item and the grand total for the order:

package MyContentHandler;

use base qw(XML::SAX::Base);

sub start_document {
      my $self = shift;
      $self->{text} = '';

      $total_price = 0;
}

sub end_document {
      print "Order total: $total_price\n";
}

sub start_element{
   my $self = shift;
   my $el = shift;

   $local_name = $el->{LocalName};
   if ($local_name eq "order") {
       my $at = $el->{Attributes}->{"{}orderid"};
       my $order_id = $at->{Value};
       my $customer_id = $el->{Attributes}->{"{}customerNumber"}->{Value};
       print "Order $order_id for customer $customer_id\n";
   } elsif ($local_name eq "lineitem"){
       $item_id = $el->{Attributes}->{"{}itemid"}->{Value};
   }

   $currentElement = $local_name;
   $self->clear_text();
}

sub end_element{
   my $self = shift;
   my $el = shift;

   my $text = $self->get_text();
   my $local_name = $el->{LocalName};

      if ($text ne '') {
         if ($local_name eq "item"){
            $item_name = $text;
         } elsif ($local_name eq "quantity"){
            $quantity = $text;
         } elsif ($local_name eq "unitprice"){
            $unit_price = $text;
         }  
      }

      if ($local_name eq "lineitem"){
         my $extended_price = $quantity * $unit_price;
         print "Item: $item_name ($item_id) $quantity @ $unit_price = $extended_price\n";
         $total_price = $total_price + $extended_price;
         $item_name = "";
         $quantity = "";
         $unitprice = "";
      }
}

sub display_text {
   my $self = shift;
   print $self->get_text();
}

sub get_text {
   my $self = shift;
   my $text = '';
   if ( defined( $self->{text} ) ) {
      $text = $self->{text};
      $self->{text} = '';
   }
   return $text;
}

sub clear_text {
   my $self = shift;
   $self->{text} = '';
}

sub characters {
    my $self = shift;
    my $text = shift;

    $self->{text} .= $text->{Data};
}


package main;

use XML::SAX;

XML::SAX->add_parser(q(XML::SAX::PurePerl));

$total_price = 0;
$item_id = '';
$current_element = '';
$item_name = '';
$quantity = '';
$unit_price = '';


my $factory = XML::SAX::ParserFactory->new();
my $parser = $factory->parser( Handler => MyContentHandler->new() );

eval { $parser->parse_uri('order.xml'); };

print "Error parsing file: $@" if $@;

In essence, this script does the same job the last one did, in that it parses the XML file and saves data so that it can act on it later. In this case, however, the script is also performing (albeit rudimentary) analysis on the streamed data. Executing it provides the result:

Order THX1138 for customer 3263827
Item: 3/4" Hex Bolt (C33) 36 @ .35 = 12.6
Item: Condenser (M48) 1 @ 2200 = 2200
Order total: 2212.6