A Basic Example¶

Other XML sources¶

The first example script called XML::LibXML->load_xml() with the location argument set to the name of a file. The location argument also accepts a URL:

$dom = XML::LibXML->load_xml(location => 'http://techcrunch.com/feed/');

If you have the XML in a string, instead of location, use string:

$dom = XML::LibXML->load_xml(string => $xml_string);

Or, you can provide a Perl file handle to parse from an open file or socket, using IO:

$dom = XML::LibXML->load_xml(IO => $fh);

When providing a string or a file handle, it’s crucial that you do not decode the bytes of the source data (for example by using ':utf8' when opening a file). The underlying libxml2 library is written in C to decode bytes and does not understand Perl’s character strings. If you have assembled your XML document by concatenating Perl character strings, you will need to encode it to a byte string (for example using Encode::encode_utf8()) and then pass the byte string to the parser.

If you have enabled UTF-8 globally with something like this in your script:

use open ':encoding(utf8)';

Then you’ll need to turn off the encoding IO layers for any file handle that you pass to XML::LibXML:

open my $fh, '<', $filename;
binmode $fh, ':raw';
$dom = XML::LibXML->load_xml(IO => $fh);

A more complex example¶

Now let’s look at a slightly more complex example. This script takes the same XML input and extracts more details from each <movie> element:

#!/usr/bin/perl

use 5.010;
use strict;
use warnings;

use XML::LibXML;

my $filename = 'playlist.xml';

my $dom = XML::LibXML->load_xml(location => $filename);

foreach my $movie ($dom->findnodes('//movie')) {
    say 'Title:    ', $movie->findvalue('./title');
    say 'Director: ', $movie->findvalue('./director');
    say 'Rating:   ', $movie->findvalue('./mpaa-rating');
    say 'Duration: ', $movie->findvalue('./running-time'), " minutes";
    my $cast = join ', ', map {
        $_->to_literal();
    } $movie->findnodes('./cast/person/@name');
    say 'Starring: ', $cast;
    say "";
}

and will produce the following output:

Title:    Apollo 13
Director: Ron Howard
Rating:   PG
Duration: 140 minutes
Starring: Tom Hanks, Bill Paxton, Kevin Bacon, Gary Sinise, Ed Harris

Title:    Solaris
Director: Steven Soderbergh
Rating:   PG-13
Duration: 99 minutes
Starring: George Clooney, Natascha McElhone, Ulrich Tukur

Title:    Ender's Game
Director: Gavin Hood
Rating:   PG-13
Duration: 114 minutes
Starring: Asa Butterfield, Harrison Ford, Hailee Steinfeld

Title:    Interstellar
Director: Christopher Nolan
Rating:   PG-13
Duration: 169 minutes
Starring: Matthew McConaughey, Anne Hathaway, Jessica Chastain, Michael Caine

Title:    The Martian
Director: Ridley Scott
Rating:   PG-13
Duration: 144 minutes
Starring: Matt Damon, Jessica Chastain, Kristen Wiig

Let’s compare the main loop of the first script:

foreach my $title ($dom->findnodes('/playlist/movie/title')) {
    say $title->to_literal();
}

with the main loop of the second script:

foreach my $movie ($dom->findnodes('//movie')) {
    say 'Title:    ', $movie->findvalue('./title');
    say 'Director: ', $movie->findvalue('./director');
    say 'Rating:   ', $movie->findvalue('./mpaa-rating');
    say 'Duration: ', $movie->findvalue('./running-time'), " minutes";
    my $cast = join ', ', map {
        $_->to_literal();
    } $movie->findnodes('./cast/person/@name');
    say 'Starring: ', $cast;
    say "";
}

The structure of the main loop is very similar but the XPath expression passed to findnodes() is different in each case:

'/playlist/movie/title'

Will match every <title> element which is the child of ...

a <movie> element which is the child of ...

a <playlist> element which is ...

the top-level element in the document.

Or, to phrase it a different way, the search will start at the top of the document and look for a <playlist> element; if one is found, the search will continue for child <movie> elements; and for each one that is found the search will continue for child <title> elements.

'//movie'

Will match every <movie> element at any level of nesting.

In both cases, the XPath expression starts with a ‘/’ which means the search will start at the the top of the document.

Inside the second script’s loop are a number of calls to findvalue(). This is a handy shortcut method that is typically used when you expect the XPath expression to match exactly one node. It combines the functionality of findnodes() and to_literal() into a single method. So this code:

$movie->findvalue('./title');

is equivalent to:

$movie->findnodes('./title')->to_literal();

There are a couple of other interesting differences with the XPath searches in the loop compared to previous examples. Firstly, the findvalue() method is being called on $movie (which represents one <movie> element) rather than on $dom (which represents the whole document). This means that the $movie element is the context element. Secondly, the XPath expression starts with a ‘.’ which means: start the search at the context element rather than at the top of the document.

This second script illustrates a common pattern when working with XML::LibXML:

1. find ‘interesting’ elements using an XPath query starting with ‘/’ or ‘//’
2. iterate through those elements in a foreach loop
3. get additional data from child elements using XPath queries starting with ‘.’

Accessing attributes¶

When listing cast members in the main loop of the script above, this code ...

    my $cast = join ', ', map {
        $_->to_literal();
    } $movie->findnodes('./cast/person/@name');
    say 'Starring: ', $cast;

is used to transform this XML ...

1
2
3
4
5

<cast>
  <person name="Matt Damon" role="Mark Watney" />
  <person name="Jessica Chastain" role="Melissa Lewis" />
  <person name="Kristen Wiig" role="Annie Montrose" />
</cast>

into this output:

Starring: Matt Damon, Jessica Chastain, Kristen Wiig

In an XPath expression, a name that starts with @ will match an attribute rather than an element, so 'person/@name' refers to an attribute called name on a <person> element. In this case, the call to findnodes('./cast/person/@name') will return three DOM nodes representing attribute values which are then transformed into plain strings using to_literal(), as we’ve seen for element nodes, inside a map block.

Another approach is to select the element with XPath and then call a DOM method on the element node to get the attribute value:

    my $cast = join ', ', map {
        $_->getAttribute('name');
    } $movie->findnodes('./cast/person');
    say 'Starring: ', $cast;

Attributes via tied hash¶

There’s a shortcut syntax you can use to make this even easier, simply treat the element node as a hashref:

    my $cast = join ', ', map {
        $_->{name};
    } $movie->findnodes('./cast/person');
    say 'Starring: ', $cast;

You might be a bit wary of poking around directly inside the element object, rather than using accessor methods. But don’t worry, that’s not what this shortcut syntax is doing. Instead, every XML::LibXML::Element object returned from the XPath query has been ‘tied’ using XML::LibXML::AttributeHash so that hash lookups ‘inside’ the object actually get proxied to getAttribute() method calls.

This technique is less efficient than calling getAttribute() directly but it is very convenient when you want to access more than one attribute of an element or when you want to interpolate an attribute value into a string:

    my $cast = join "\n", map {
        " * $_->{name} (as $_->{role})";
    } $movie->findnodes('./cast/person');
    say "\nStarring:\n", $cast;

Which will produce this output:

Starring:
 * Matt Damon (as Mark Watney)
 * Jessica Chastain (as Melissa Lewis)
 * Kristen Wiig (as Annie Montrose)

Parsing Errors¶

One of the advantages of XML is that it has a few strict rules that every document must comply with to be considered “well-formed”. If a document is not well-formed, it should be rejected in its entirety and no part of the XML document content should be used. Examples of things that would cause a document to be not well-formed include:

• missing or mismatched closing tag
• missing or mismatched quotes around attribute values
• whitespace before the initial XML declaration section
• byte sequences that do not match the document’s declared character encoding
• any non-whitespace characters after the closing tag for the first top-level element

Like pretty much all XML parser modules, libxml will throw an exception if it encounters any violations of these rules. Since the whole of the XML document is processed when load_xml is called, an error at any point in the document will cause an exception to be raised.

If you wish to handle exceptions gracefully use must use an eval block or one of the “try/catch” syntax extension modules to catch the error. For example, this document contains an error:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<?xml version='1.0' encoding='UTF-8' standalone="yes" ?>
<book edition="2">
  <title>Training Your Pet Ferret</title>
  <authors>
    <author>Gerry Bucsis</author>
    <author>Barbara Somerville</author>
  </authors>
  <isbn>9780764142239</isnb>
  <dimensions width="162.56mm" height="195.58mm" depth="10.16mm" pages="96" />
</book>

This script will attempt to parse the bad input:

#my $filename = 'book.xml';
my $filename = 'book-borkened.xml';

my $dom = eval {
    XML::LibXML->load_xml(location => $filename);
};
if($@) {
    # Log failure and exit
    print "Error parsing '$filename':\n$@";
    exit 0;
}

foreach my $author ($dom->findnodes('//author')) {
    say $author->to_literal();

and will instead produce this output:

Error parsing 'book-borkened.xml':
book-borkened.xml:8: parser error : Opening and ending tag mismatch: isbn line 8 and isnb
  <isbn>9780764142239</isnb>
                            ^

Note that although the script is only looking for <author> elements and the error in the <isbn> element comes after all the <author> elements, an exception is still raised by the load_xml call inside the eval block, before the DOM has been fully constructed.

That’s it for the basic examples. The next topic will look more closely at XPath expressions.