NAME

XML::Saxtract - Streaming parse XML data into a result hash based upon a specification hash

VERSION

version 1.04

SYNOPSIS

use XML::Saxtract qw(saxtract_string saxtract_uri);

my $xml = "<root id='1' />";
my $spec = { '/root/@id' => rootId };

my $result = saxtract_string( $xml, $spec );
my $rootId = $result->{rootId};

my $complex_xml = <<'XML';
<root xmlns='http://abc' xmlns:d='http://def' d:id='1' name='root' d:other='abc'>
  <person id='1'>Lucas</person>
  <d:employee id='2'>Ali</d:employee>
  <person id='3'>Boo</person>
  <d:employee id='4'>Dude</d:employee>
</root>
XML

# get the first person
my $complex_spec = {
    'http://def' => 'k',
    '/root/person' => {
        name => 'first_person',
        type => 'first',
        spec => {
            '' => 'name',
            '/@id' => 'id'
        }
    }
};
my $result = saxtract_string( $complex_xml, $complex_spec );
print( "$result->{first_person}{id}: $result->{first_person}{name}\n" );
# Prints:
# 1: Lucas

# get a array of all the people
my $complex_spec = {
    'http://def' => 'k',
    '/root/person' => {
        name => 'people',
        type => 'array',
        spec => {
            '' => 'name',
            '/@id' => 'id'
        }
    }
};
my $result = saxtract_string( $complex_xml, $complex_spec );
foreach my $person ( @{$result->{people}} ) {
    print( "$person->{id}: $person->{name}\n" );
}
# Prints:
# 1: Lucas
# 3: Boo

# get a map of all the employees
my $complex_spec = {
    'http://def' => 'k',
    '/root/k:employee' => {
        name => 'employees',
        type => 'map',
        key => 'name',
        spec => {
            '' => sub {
                my ($object, $value) = @_;
                $object->{name} => $value;
                $object->{email} => lc($value) . '@example.com';
            },
            '/@id' => 'id'
        }
    }
};
my $result = saxtract_string( $complex_xml, $complex_spec );
foreach my $employee ( values( %{$result->{employees}} ) ) {
    print( "$employee->{id}: $employee->{name} <$employee->{email}>\n" );
}
# Prints:
# 2: Ali <ali@example.com>
# 4: Dude <dude@example.com>

# get a map of all the employees generating a compound key
my $complex_spec = {
    'http://def' => 'k',
    '/root/k:employee' => {
        name => 'employees',
        type => sub {
            my ( $object, $value ) = @_;
            $object->{"$value->{id}|$value->{name}"} = $value;
        },
        spec => {
            '' => sub {
                my ($object, $value) = @_;
                $object->{name} => $value;
                $object->{email} => lc($value) . '@example.com';
            },
            '/@id' => 'id'
        }
    }
};
my $result = saxtract_string( $complex_xml, $complex_spec );
foreach my $compound_key ( keys( %{$result->{employees}} ) ) {
    print( "$compound_key: <$result->{employees}{$compund_key}{email}>\n" );
}
# Prints:
# 2|Ali: <ali@example.com>
# 4|Dude: <dude@example.com>

DESCRIPTION

This module provides methods for SAX based (streaming) parsing of XML data into a result hash based upon a specification hash.

EXPORT_OK

saxtract_string( $xml_string, $specification, [%options] )

Parses the xml_string according to the specification optionally setting values in the result object. If the result object is not specified, a new empty hash is created and a reference to it is returned.

xml_string

A string containing the xml to be parsed.

specification

A Saxtract specification hash.

options

object

A reference to a hash to load with the results of the parsing.

saxtract_url( $url, $specification, [%options] )

Parses the xml_string according to the specification optionally setting values in the result object. If the result object is not specified, a new empty hash is created and a reference to it is returned.

url

A URL used to locate the XML content. LWP::UserAgent will be used to retrieve the content from this URL.

specification

A Saxtract specification hash.

options

object

A reference to a hash to load with the results of the parsing.

agent

If specified, this agent will be used to request the XML, if not, a new LWP::UserAgent will be used.

die_on_failure

If true, the request will die on any http response other than 200. $@ will be set to the HTTP::Response object returned by the request.

AUTHOR

Lucas Theisen <lucastheisen@pastdev.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Lucas Theisen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.