/ 
XML-Toolset-0.50
River stage zero No dependents
/ XML::Toolset

NAME

XML::Toolset - perform XML construction, parsing, validation, and XPath operations using whatever underlying XML library is available (ALPHA!)

SYNOPSIS

use App;
use XML::Toolset;

my $context = App->context();
my $toolset = $context->xml_toolset(class => "XML::Toolset::BestAvailable");

...

DESCRIPTION

The XML-Toolset distribution is a wrapper which provides a simplified XML processing API which uses XPath to construct and dissect XML messages.

The architecture of the XML-Toolset distribution allows for the user of the API to access XML capabilities independent of the underlying XML toolset technology: i.e. Xerces, LibXML, XML::XMLDOM, MSXML.

SYNOPSIS

NOTE: Everything after this is out of date and needs review.

my $toolset = new XML::Toolset(type => 'LibXML');

if ($toolset->validate($xml)) {
  print "Document is valid\n";
} else {
  print "Document is invalid\n";
  my $message = $toolset->last_error()->{message};
  my $line = $toolset->last_error()->{line};
  my $column = $toolset->last_error()->{column};
  print "Error: $message at line $line, column $column\n";
}

DESCRIPTION

XML::Toolset is a generic interface to different XML validation backends. For a list of backend included with this distribution see the README.

If you want to write your own backends, the easiest way is probably to subclass XML::Toolset::Base. Look at the existing backends for examples.

METHODS

new(type => $type, options => \%options)

Returns a new XML::Toolset parser object of type $type. For available types see README or use 'BestAvailable' (see "BEST AVAILABLE").

The optional argument "options" can be used to supply a set of key-value pairs to the backend parser. See the documentation for individual backends for details of these options.

validate_document($xml_string)

Attempts a validating parse of the XML document $xml_string and returns a true value on success, or undef otherwise. If the parse fails, the error can be inspected using last_error.

Note that documents which don't specify a DTD or schema will be treated as valid.

For DOM-based parsers, the DOM may be accessed by instantiating the backend module directly and calling the last_dom method - consult the documentation of the specific backend modules. Note that this isn't formally part of the XML::Toolset interface as non-DOM-based validators may added at some point.

last_error()

Returns the error from the last validate call. This is a hash ref with the following fields:

  • message

  • line

  • column

Note that the error gets cleared at the beginning of each validate call.

type()

Returns the type of backend being used.

version()

Returns the version of the backend

ERROR REPORTING

When a call to validate fails to parse the document, the error may be retrieved using last_error.

On errors not related to the XML parsing, methods will throw exceptions. Wrap calls with eval to catch them.

BEST AVAILABLE

The BestAvailable backend type will check which backends are available and give you the "best" of those. For the default order of preference see the README with this distribution, but this can be changed with the option "prioritized_list".

If Xerces and LibXML are available the following code will give you a LibXML backend:

my $toolset = new XML::Toolset(
    type => 'BestAvailable',
    options => { prioritized_list => [ qw( MSXML LibXML Xerces ) ] },
);

KNOWN ISSUES

There is a bug in versions 1.57 and 1.58 of XML::LibXML that causes an issue related to DTD loading. When a base parameter is used in conjunction with the load_ext_dtd method the base parameter is ignored and the current directory is used as the base parameter. In other words, when validating XML with LibXML any base parameter option will be ignored, which may result in unexpected DTD loading errors. This was reported as bug on November 30th 2005 and the bug report can be viewed here http://rt.cpan.org/Public/Bug/Display.html?id=16213

AUTHORS

Stephen Adkins <spadkins@gmail.com>

Original Code (XML::Validate): Nathan Carr, Colin Robertson (see XML::Validate) <cpan _at_ bbc _dot_ co _dot_ uk>

COPYRIGHT

(c) 2007 Stephen Adkins. XML-Toolset is derived from XML-Validate under the terms of the GNU GPL. (c) 2005 BBC. XML-Toolset is derived from XML-Validate. XML-Validate is free software; you can redistribute it and/or modify it under the GNU GPL. See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt