XML::LibXML::InputCallback man page on OpenServer

Man page or keyword search:  
man Server   5388 pages
apropos Keyword Search (all sections)
Output format
OpenServer logo
[printable version]

XML::LibXML::InputCallUser(Contributed Perl DocumXML::LibXML::InputCallback(3)

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

SYNOPSIS
	 my $input_callbacks = XML::LibXML::InputCallback->new();
	 $input_callbacks->register_callbacks([ $match_cb1, $open_cb1,
						$read_cb1, $close_cb1 ] );
	 $input_callbacks->register_callbacks([ $match_cb2, $open_cb2,
						$read_cb2, $close_cb2 ] );
	 $input_callbacks->register_callbacks( [ $match_cb3, $open_cb3,
						 $read_cb3, $close_cb3 ] );

	 $parser->input_callbacks( $input_callbacks );
	 $parser->parse_file( $some_xml_file );

DESCRIPTION
       You may get unexpected results if you are trying to load external docu-
       ments during libxml2 parsing if the location of the resource 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.

       How does XML::LibXML::InputCallback work?

       The libxml2 library offers a callback implementation as global func-
       tions 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 Web-server 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, opera-
       tions for working with the "pseudo-localized" callback stack are imple-
       mented. Currently, you can register and de-register callbacks on the
       Perl layer and initialize them on a per parser basis.

       Using XML::LibXML::InputCallback

       After object instantiation using the parameter-less constructor, you
       can register callback groups.

	 my $input_callbacks = XML::LibXML::InputCallback->new();
	 $input_callbacks->register_callbacks([ $match_cb1, $open_cb1,
						$read_cb1, $close_cb1 ] );
	 $input_callbacks->register_callbacks([ $match_cb2, $open_cb2,
						$read_cb2, $close_cb2 ] );
	 $input_callbacks->register_callbacks( [ $match_cb3, $open_cb3,
						 $read_cb3, $close_cb3 ] );

	 $parser->input_callbacks( $input_callbacks );
	 $parser->parse_file( $some_xml_file );

       What about the old callback system prior to XML::LibXML::InputCallback?

       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 call-
       back 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
       Global Variables

       $_CUR_CB
	   Stores the current callback and can be used as shortcut to access
	   the callback stack.

       @_GLOBAL_CALLBACKS
	   Stores all callback groups for the current parser process.

       @_CB_STACK
	   Stores the currently used callback group. Used to prevent parser
	   errors when dealing with nested XML data.

       Global Callbacks

       _callback_match
	   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.

       _callback_open
	   Forwards the open callback from libxml2 to the corresponding call-
	   back function at the Perl-level.

       _callback_read
	   Forwards the read request to the corresponding callback function at
	   the Perl-level and returns the result to libxml2.

       _callback_close
	   Forwards the close callback from libxml2 to the corresponding call-
	   back function at the Perl-level..

       Class methods

       new()
	   A simple constructor.

       register_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])
	   The four callbacks have to be given as array reference in the above
	   order match, open, read, close!

       unregister_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])
	   With no arguments given, unregister_callbacks() 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 call-
	   back stack. Note that if several identical match callbacks are
	   defined in different callback groups, ALL of them will be deleted
	   from the stack.

       init_callbacks()
	   Initializes the callback system before a parsing process.

       cleanup_callbacks()
	   Resets global variables and the libxml2 callback stack.

       lib_init_callbacks()
	   Used internally for callback registration at C-level.

       lib_cleanup_callbacks()
	   Used internally for callback resetting at the C-level.

EXAMPLE CALLBACKS
       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 match_uri {
	     my $uri = shift;
	     return $uri =~ /^myscheme:/; # trigger our callback group at a 'myscheme' URIs
	 }

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

	 # The returned $buffer will be parsed by the libxml2 parser
	 sub read_uri {
	     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 close_uri {
	     my $handler = shift;
	     close($handler);
	 }

	 # Register them with a instance of XML::LibXML::InputCallback
	 my $input_callbacks = XML::LibXML::InputCallback->new();
	 $input_callbacks->register_callbacks([ \&match_uri, \&open_uri,
						\&read_uri, \&close_uri ] );

	 # Register the callback group at a parser instance
	 $parser->input_callbacks( $input_callbacks );

	 # $some_xml_file will be parsed using our callbacks
	 $parser->parse_file( $some_xml_file );

AUTHORS
       Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION
       1.63

COPYRIGHT
       2001-2007, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006-2007 Petr
       Pajas, All rights reserved.

perl v5.8.8			  2007-04-16	 XML::LibXML::InputCallback(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server OpenServer

List of man pages available for OpenServer

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net