Manual Pages for UNIX Darwin command on man XML::LibXML::InputCallback

XML::LibXML::InputCallbUascekr(3C)ontributed Perl DocumeXnMtLa:t:iLoinbXML::InputCallback(3)

NAME

XML::LibXML::InputCallback - XML::LibXML Class for Input Callbacks

SYNOPSIS

my $inputcallbacks = XML::LibXML::InputCallback->new();

$inputcallbacks->registercallbacks([ $matchcb1, $opencb1,

$readcb1, $closecb1 ] );

$inputcallbacks->registercallbacks([ $matchcb2, $opencb2,

$readcb2, $closecb2 ] );

$inputcallbacks->registercallbacks( [ $matchcb3, $opencb3,

$readcb3, $closecb3 ] );

$parser->inputcallbacks( $inputcallbacks );

$parser->parsefile( $somexmlfile );

DESCRIPTION

You may get unexpected results if you are trying to load external documents during libxml2 parsing if the location of the ressource is not a HTTP, FTP or relative location but a absolute path for example. To get around this limitation, you may add your own input handler to open, read and close particular types of locations or URI classes. Using this input callback handlers, you can handle your own custom URI schemes for example. The input callbacks are used whenever LibXML has to get something other than externally parsed entities from somewhere. They are implemented using a callback stack on the Perl layer in analogy to libxml2's native callback stack.

The XML::LibXML::InputCallback class transparently registers the input

callbacks for the libxml2's parser processes. HHooww ddooeess XXMMLL::::LLiibbXXMMLL::::IInnppuuttCCaallllbbaacckk wwoorrkk?? The libxml2 library offers a callback implementation as global

functions only. To work-around the troubles resulting in having only

global callbacks - for example, if the same global callback stack is

manipulated by different applications running together in a single

Apache Webserver environment -, XML::LibXML::InputCallback comes with a

object-oriented and a function-oriented part.

Using the function-oriented part the global callback stack of libxml2

can be manipulated. Those functions can be used as interface to the

callbacks on the C- and XS Layer. At the object-oriented part,

operations for working with the "pseudo-localized" callback stack are

implemented. Currently, you can register and de-register callbacks on

the Perl layer and initialize them on a per parser basis. UUssiinngg XXMMLL::::LLiibbXXMMLL::::IInnppuuttCCaallllbbaacckk

After object instantiation using the parameter-less constructor, you

can register callback groups.

my $inputcallbacks = XML::LibXML::InputCallback->new();

$inputcallbacks->registercallbacks([ $matchcb1, $opencb1,

$readcb1, $closecb1 ] );

$inputcallbacks->registercallbacks([ $matchcb2, $opencb2,

$readcb2, $closecb2 ] );

$inputcallbacks->registercallbacks( [ $matchcb3, $opencb3,

$readcb3, $closecb3 ] );

$parser->inputcallbacks( $inputcallbacks );

$parser->parsefile( $somexmlfile );

WWhhaatt aabboouutt tthhee oolldd ccaallllbbaacckk ssyysstteemm pprriioorr ttoo XXMMLL::::LLiibbXXMMLL::::IInnppuuttCCaallllbbaacckk??

In XML::LibXML versions prior to 1.59 - i.e. without the

XML::LibXML::InputCallback module - you could define your callbacks

either using globally or locally. You still can do that using

XML::LibXML::InputCallback, and in addition to that you can define the

callbacks on a per parser basis! If you use the old callback interface through global callbacks,

XML::LibXML::InputCallback will treat them with a lower priority as the

ones registered using the new interface. The global callbacks will not override the callback groups registered using the new interface. Local callbacks are attached to a specific parser instance, therefore they are treated with highest priority. If the match callback of the callback group registered as local variable is identical to one of the callback groups registered using the new interface, that callback group will be replaced. Users of the old callback implementation whose open callback returned a plain string, will have to adapt their code to return a reference to that string after upgrading to version >= 1.59. The new callback system can only deal with the open callback returning a reference!

INTERFACE DESCRIPTION

GGlloobbaall VVaarriiaabblleess

$$CCUURRCCBB

Stores the current callback and can be used as shortcut to access the callback stack. @@GGLLOOBBAALLCCAALLLLBBAACCKKSS Stores all callback groups for the current parser process. @@CCBBSSTTAACCKK Stores the currently used callback group. Used to prevent parser errors when dealing with nested XML data. GGlloobbaall CCaallllbbaacckkss ccaallllbbaacckkmmaattcchh

Implements the interface for the match callback at C-level and for

the selection of the callback group from the callbacks defined at

the Perl-level.

ccaallllbbaacckkooppeenn Forwards the open callback from libxml2 to the corresponding

callback function at the Perl-level.

ccaallllbbaacckkrreeaadd Forwards the read request to the corresponding callback function at

the Perl-level and returns the result to libxml2.

ccaallllbbaacckkcclloossee Forwards the close callback from libxml2 to the corresponding

callback function at the Perl-level..

CCllaassss mmeetthhooddss nneeww(()) A simple constructor.

rreeggiisstteerrccaallllbbaacckkss(( [[ $$mmaattcchhccbb,, $$ooppeennccbb,, $$rreeaaddccbb,, $$cclloosseeccbb ]]))

The four callbacks have to be given as array reference in the above order match, open, read, close!

uunnrreeggiisstteerrccaallllbbaacckkss(( [[ $$mmaattcchhccbb,, $$ooppeennccbb,, $$rreeaaddccbb,, $$cclloosseeccbb ]]))

With no arguments given, unregistercallbacks() will delete the last registered callback group from the stack. If four callbacks are passed as array reference, the callback group to unregister will be identified by the match callback and deleted from the callback stack. Note that if several identical match callbacks are defined in different callback groups, ALL of them will be deleted from the stack. iinniittccaallllbbaacckkss(()) Initializes the callback system before a parsing process. cclleeaannuuppccaallllbbaacckkss(()) Resets global variables and the libxml2 callback stack. lliibbiinniittccaallllbbaacckkss(())

Used internally for callback registration at C-level.

lliibbcclleeaannuuppccaallllbbaacckkss(())

Used internally for callback resetting at the C-level.

EEXXAAMMPPLLEE CCAALLLLBBAACCKKSS The following example is a purely fictitious example that uses a MyScheme::Handler object that responds to methods similar to an IO::Handle.

# Define the four callback functions

sub matchuri {

my $uri = shift;

return $uri =~ /^myscheme:/; # trigger our callback group at a 'myscheme' URIs

} sub openuri {

my $uri = shift;

my $handler = MyScheme::Handler->new($uri);

return $handler;

}

# The returned $buffer will be parsed by the libxml2 parser

sub readuri {

my $handler = shift;

my $length = shift;

my $buffer;

read($handler, $buffer, $length);

return $buffer; # $buffer will be an empty string '' if read() is done

}

# Close the handle associated with the resource.

sub closeuri {

my $handler = shift;

close($handler);

}

# Register them with a instance of XML::LibXML::InputCallback

my $inputcallbacks = XML::LibXML::InputCallback->new();

$inputcallbacks->registercallbacks([ \&matchuri, \&openuri,

\&readuri, \&closeuri ] );

# Register the callback group at a parser instance

$parser->inputcallbacks( $inputcallbacks );

# $somexmlfile will be parsed using our callbacks

$parser->parsefile( $somexmlfile );

AUTHORS Matt Sergeant, Christian Glahn, Petr Pajas, VVEERRSSIIOONN 1.60 COPYRIGHT

2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas,