/ 
XML-LibXSLT-0.97
River stage two • 53 direct dependents • 86 total dependents
/ XML::LibXML

NAME

XML::LibXML - Interface to the gnome libxml2 library

SYNOPSIS

use XML::LibXML;
my $parser = XML::LibXML->new();

my $doc = $parser->parse_string(<<'EOT');
<xml/>
EOT

DESCRIPTION

Currently this module doesn't actually do much but parse files and give you back a document (DOM) handle. You can't actually call DOM methods on that document though (because I haven't written the code to do it yet!).

OPTIONS

LibXML options are global (unfortunately this is a limitation of the underlying implementation, not this interface). They can either be set using $parser->option(...), or XML::LibXML->option(...), both are treated in the same manner. Note that even two forked processes will share some of the same options, so be careful out there!

Every option returns the previous value, and can be called without parameters to get the current value.

validation

XML::LibXML->validation(1);

Turn validation on (or off). Defaults to off.

expand_entities

XML::LibXML->expand_entities(0);

Turn entity expansion on or off, enabled by default. If entity expansion is off, any external parsed entities in the document are left as entities. Probably not very useful for most purposes.

keep_blanks

XML::LibXML->keep_blanks(0);

Allows you to turn off XML::LibXML's default behaviour of maintaining whitespace in the document.

pedantic_parser

XML::LibXML->pedantic_parser(1);

You can make XML::LibXML more pedantic if you want to.

load_ext_dtd

XML::LibXML->load_ext_dtd(1);

Load external DTD subsets while parsing.

match_callback

XML::LibXML->match_callback($subref);

Sets a "match" callback. See "Input Callbacks" below.

open_callback

XML::LibXML->open_callback($subref);

Sets an open callback. See "Input Callbacks" below.

read_callback

XML::LibXML->read_callback($subref);

Sets a read callback. See "Input Callbacks" below.

close_callback

XML::LibXML->close_callback($subref);

Sets a close callback. See "Input Callbacks" below.

CONSTRUCTOR

The XML::LibXML constructor, new(), takes the following parameters:

ext_ent_handler

my $parser = XML::LibXML->new(ext_ent_handler => sub { ... });

The ext_ent_handler sub is called whenever libxml needs to load an external parsed entity. The handler sub will be passed two parameters: a URL (SYSTEM identifier) and an ID (PUBLIC identifier). It should return a string containing the resource at the given URI.

Note that you do not need to enable this - if not supplied libxml will get the resource either directly from the filesystem, or using an internal http client library.

PARSING

There are three ways to parse documents - as a string, as a Perl filehandle, or as a filename. The return value from each is a XML::LibXML::Document object, which is a DOM object (although no DOM methods are implemented yet). See "XML::LibXML::Document" below for more details on the methods available on documents.

Each of the below methods will throw an exception if the document is invalid. To prevent this causing your program exiting, wrap the call in an eval{} block.

parse_string

my $doc = $parser->parse_string($string);

parse_fh

my $doc = $parser->parse_fh($fh);

Here, $fh can be an IOREF, or a subclass of IO::Handle.

parse_file

my $doc = $parser->parse_file($filename);

XML::LibXML::Document

The objects returned above have a few methods available to them:

$doc->toString

Convert the document to a string.

$doc->is_valid

Post parse validation. Returns true if the document is valid against the DTD specified in the DOCTYPE declaration

$doc->is_valid($dtd)

Same as the above, but allows you to pass in a DTD created from "XML::LibXML::Dtd".

$doc->process_xinclude

Process any xinclude tags in the file.

XML::LibXML::Dtd

This module allows you to parse and return a DTD object. It has one method right now, new().

new()

my $dtd = XML::LibXML::Dtd->new($public, $system);

Creates a new DTD object from the public and system identifiers. It will automatically load the objects from the filesystem, or use the input callbacks (see "Input Callbacks" below) to load the DTD.

Input Callbacks

The input callbacks are used whenever LibXML has to get something other than external parsed entities from somewhere. The input callbacks in LibXML are stacked on top of the original input callbacks within the libxml library. This means that if you decide not to use your own callbacks (see match()), then you can revert to the default way of handling input. This allows, for example, to only handle certain URI schemes.

The following callbacks are defined:

match(uri)

If you want to handle the URI, simply return a true value from this callback.

open(uri)

Open something and return it to handle that resource.

read(handle, bytes)

Read a certain number of bytes from the resource.

close(handle)

Close the handle associated with the resource.

Example

This is a purely fictitious example that uses a MyScheme::Handler object that responds to methods similar to an IO::Handle.

XML::LibXML->match_callback(\&match_uri);

XML::LibXML->open_callback(\&open_uri);

XML::LibXML->read_callback(\&read_uri);

XML::LibXML->close_callback(\&close_uri);

sub match_uri {
  my $uri = shift;
  return $uri =~ /^myscheme:/;
}

sub open_uri {
  my $uri = shift;
  return MyScheme::Handler->new($uri);
}

sub read_uri {
  my $handler = shift;
  my $length = shift;
  my $buffer;
  read($handler, $buffer, $length);
  return $buffer;
}

sub close_uri {
  my $handler = shift;
  close($handler);
}

AUTHOR

Matt Sergeant, matt@sergeant.org

Copyright 2001, AxKit.com Ltd. All rights reserved.

SEE ALSO

XML::LibXSLT