1XML::LibXML::InputCallbUascekr(3C)ontributed Perl DocumeXnMtLa:t:iLoinbXML::InputCallback(3)
2
6 XML::LibXML::InputCallback - XML::LibXML Class for Input Callbacks
7
9 my $input_callbacks = XML::LibXML::InputCallback->new();
10 $input_callbacks->register_callbacks([ $match_cb1, $open_cb1,
11 $read_cb1, $close_cb1 ] );
12 $input_callbacks->register_callbacks([ $match_cb2, $open_cb2,
13 $read_cb2, $close_cb2 ] );
14 $input_callbacks->register_callbacks( [ $match_cb3, $open_cb3,
15 $read_cb3, $close_cb3 ] );
16 $parser->input_callbacks( $input_callbacks );
18 $parser->parse_file( $some_xml_file );
19
21 You may get unexpected results if you are trying to load external docu‐
22 ments during libxml2 parsing if the location of the ressource is not a
23 HTTP, FTP or relative location but a absolute path for example. To get
24 around this limitation, you may add your own input handler to open,
25 read and close particular types of locations or URI classes. Using this
26 input callback handlers, you can handle your own custom URI schemes for
27 example.
28 The input callbacks are used whenever LibXML has to get something other
30 than externally parsed entities from somewhere. They are implemented
31 using a callback stack on the Perl layer in analogy to libxml2's native
32 callback stack.
33 The XML::LibXML::InputCallback class transparently registers the input
35 callbacks for the libxml2's parser processes.
36 How does XML::LibXML::InputCallback work?
38 The libxml2 library offers a callback implementation as global func‐
40 tions only. To work-around the troubles resulting in having only
41 global callbacks - for example, if the same global callback stack is
42 manipulated by different applications running together in a single
43 Apache Webserver environment -, XML::LibXML::InputCallback comes with a
44 object-oriented and a function-oriented part.
45 Using the function-oriented part the global callback stack of libxml2
47 can be manipulated. Those functions can be used as interface to the
48 callbacks on the C- and XS Layer. At the object-oriented part, opera‐
49 tions for working with the "pseudo-localized" callback stack are imple‐
50 mented. Currently, you can register and de-register callbacks on the
51 Perl layer and initialize them on a per parser basis.
52 Using XML::LibXML::InputCallback
54 After object instantiation using the parameter-less constructor, you
56 can register callback groups.
57 my $input_callbacks = XML::LibXML::InputCallback->new();
59 $input_callbacks->register_callbacks([ $match_cb1, $open_cb1,
60 $read_cb1, $close_cb1 ] );
61 $input_callbacks->register_callbacks([ $match_cb2, $open_cb2,
62 $read_cb2, $close_cb2 ] );
63 $input_callbacks->register_callbacks( [ $match_cb3, $open_cb3,
64 $read_cb3, $close_cb3 ] );
65 $parser->input_callbacks( $input_callbacks );
67 $parser->parse_file( $some_xml_file );
68 What about the old callback system prior to XML::LibXML::InputCallback?
70 In XML::LibXML versions prior to 1.59 - i.e. without the
72 XML::LibXML::InputCallback module - you could define your callbacks
73 either using globally or locally. You still can do that using
74 XML::LibXML::InputCallback, and in addition to that you can define the
75 callbacks on a per parser basis!
76 If you use the old callback interface through global callbacks,
78 XML::LibXML::InputCallback will treat them with a lower priority as the
79 ones registered using the new interface. The global callbacks will not
80 override the callback groups registered using the new interface. Local
81 callbacks are attached to a specific parser instance, therefore they
82 are treated with highest priority. If the match callback of the call‐
83 back group registered as local variable is identical to one of the
84 callback groups registered using the new interface, that callback group
85 will be replaced.
86 Users of the old callback implementation whose open callback returned a
88 plain string, will have to adapt their code to return a reference to
89 that string after upgrading to version >= 1.59. The new callback system
90 can only deal with the open callback returning a reference!
91
93 Global Variables
94 $_CUR_CB
96 Stores the current callback and can be used as shortcut to access
97 the callback stack.
98 @_GLOBAL_CALLBACKS
100 Stores all callback groups for the current parser process.
101 @_CB_STACK
103 Stores the currently used callback group. Used to prevent parser
104 errors when dealing with nested XML data.
105 Global Callbacks
107 _callback_match
109 Implements the interface for the match callback at C-level and for
110 the selection of the callback group from the callbacks defined at
111 the Perl-level.
112 _callback_open
114 Forwards the open callback from libxml2 to the corresponding call‐
115 back function at the Perl-level.
116 _callback_read
118 Forwards the read request to the corresponding callback function at
119 the Perl-level and returns the result to libxml2.
120 _callback_close
122 Forwards the close callback from libxml2 to the corresponding call‐
123 back function at the Perl-level..
124 Class methods
126 new()
128 A simple constructor.
129 register_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])
131 The four callbacks have to be given as array reference in the above
132 order match, open, read, close!
133 unregister_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])
135 With no arguments given, unregister_callbacks() will delete the
136 last registered callback group from the stack. If four callbacks
137 are passed as array reference, the callback group to unregister
138 will be identified by the match callback and deleted from the call‐
139 back stack. Note that if several identical match callbacks are
140 defined in different callback groups, ALL of them will be deleted
141 from the stack.
142 init_callbacks()
144 Initializes the callback system before a parsing process.
145 cleanup_callbacks()
147 Resets global variables and the libxml2 callback stack.
148 lib_init_callbacks()
150 Used internally for callback registration at C-level.
151 lib_cleanup_callbacks()
153 Used internally for callback resetting at the C-level.
154
156 The following example is a purely fictitious example that uses a
157 MyScheme::Handler object that responds to methods similar to an
158 IO::Handle.
159 # Define the four callback functions
161 sub match_uri {
162 my $uri = shift;
163 return $uri =~ /^myscheme:/; # trigger our callback group at a 'myscheme' URIs
164 }
165 sub open_uri {
167 my $uri = shift;
168 my $handler = MyScheme::Handler->new($uri);
169 return $handler;
170 }
171 # The returned $buffer will be parsed by the libxml2 parser
173 sub read_uri {
174 my $handler = shift;
175 my $length = shift;
176 my $buffer;
177 read($handler, $buffer, $length);
178 return $buffer; # $buffer will be an empty string '' if read() is done
179 }
180 # Close the handle associated with the resource.
182 sub close_uri {
183 my $handler = shift;
184 close($handler);
185 }
186 # Register them with a instance of XML::LibXML::InputCallback
188 my $input_callbacks = XML::LibXML::InputCallback->new();
189 $input_callbacks->register_callbacks([ \&match_uri, \&open_uri,
190 \&read_uri, \&close_uri ] );
191 # Register the callback group at a parser instance
193 $parser->input_callbacks( $input_callbacks );
194 # $some_xml_file will be parsed using our callbacks
196 $parser->parse_file( $some_xml_file );
197
199 Matt Sergeant, Christian Glahn, Petr Pajas,
200
202 1.62
203
205 2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas,
206 All rights reserved.
207perl v5.8.8 2006-11-17 XML::LibXML::InputCallback(3)