1XML::LibXML::InputCallbUascekr(3C)ontributed Perl DocumeXnMtLa:t:iLoinbXML::InputCallback(3)
2
6 XML::LibXML::InputCallback - XML::LibXML Class for Input Callbacks
7
9 use XML::LibXML;
10
12 You may get unexpected results if you are trying to load external
13 documents during libxml2 parsing if the location of the resource is not
14 a HTTP, FTP or relative location but a absolute path for example. To
15 get around this limitation, you may add your own input handler to open,
16 read and close particular types of locations or URI classes. Using this
17 input callback handlers, you can handle your own custom URI schemes for
18 example.
19 The input callbacks are used whenever LibXML has to get something other
21 than externally parsed entities from somewhere. They are implemented
22 using a callback stack on the Perl layer in analogy to libxml2's native
23 callback stack.
24 The XML::LibXML::InputCallback class transparently registers the input
26 callbacks for the libxml2's parser processes.
27 How does XML::LibXML::InputCallback work?
29 The libxml2 library offers a callback implementation as global
30 functions only. To work-around the troubles resulting in having only
31 global callbacks - for example, if the same global callback stack is
32 manipulated by different applications running together in a single
33 Apache Web-server environment -, XML::LibXML::InputCallback comes with
34 a object-oriented and a function-oriented part.
35 Using the function-oriented part the global callback stack of libxml2
37 can be manipulated. Those functions can be used as interface to the
38 callbacks on the C- and XS Layer. At the object-oriented part,
39 operations for working with the "pseudo-localized" callback stack are
40 implemented. Currently, you can register and de-register callbacks on
41 the Perl layer and initialize them on a per parser basis.
42 Callback Groups
44 The libxml2 input callbacks come in groups. One group contains a URI
46 matcher (match), a data stream constructor (open), a data stream reader
47 (read), and a data stream destructor (close). The callbacks can be
48 manipulated on a per group basis only.
49 The Parser Process
51 The parser process work on a XML data stream, along which, links to
53 other resources can be embedded. This can be links to external DTDs or
54 XIncludes for example. Those resources are identified by URIs. The
55 callback implementation of libxml2 assumes that one callback group can
56 handle a certain amount of URIs and a certain URI scheme. Per default,
57 callback handlers for file://*, file:://*.gz, http://* and ftp://* are
58 registered.
59 Callback groups in the callback stack are processed from top to bottom,
61 meaning that callback groups registered later will be processed before
62 the earlier registered ones.
63 While parsing the data stream, the libxml2 parser checks if a
65 registered callback group will handle a URI - if they will not, the URI
66 will be interpreted as file://URI. To handle a URI, the match callback
67 will have to return '1'. If that happens, the handling of the URI will
68 be passed to that callback group. Next, the URI will be passed to the
69 open callback, which should return a reference to the data stream if it
70 successfully opened the file, '0' otherwise. If opening the stream was
71 successful, the read callback will be called repeatedly until it
72 returns an empty string. After the read callback, the close callback
73 will be called to close the stream.
74 Organisation of callback groups in XML::LibXML::InputCallback
76 Callback groups are implemented as a stack (Array), each entry holds a
78 reference to an array of the callbacks. For the libxml2 library, the
79 XML::LibXML::InputCallback callback implementation appears as one
80 single callback group. The Perl implementation however allows to manage
81 different callback stacks on a per libxml2-parser basis.
82 Using XML::LibXML::InputCallback
84 After object instantiation using the parameter-less constructor, you
85 can register callback groups.
86 my $input_callbacks = XML::LibXML::InputCallback->new();
88 $input_callbacks->register_callbacks([ $match_cb1, $open_cb1,
89 $read_cb1, $close_cb1 ] );
90 $input_callbacks->register_callbacks([ $match_cb2, $open_cb2,
91 $read_cb2, $close_cb2 ] );
92 $input_callbacks->register_callbacks( [ $match_cb3, $open_cb3,
93 $read_cb3, $close_cb3 ] );
94 $parser->input_callbacks( $input_callbacks );
96 $parser->parse_file( $some_xml_file );
97 What about the old callback system prior to XML::LibXML::InputCallback?
99 In XML::LibXML versions prior to 1.59 - i.e. without the
100 XML::LibXML::InputCallback module - you could define your callbacks
101 either using globally or locally. You still can do that using
102 XML::LibXML::InputCallback, and in addition to that you can define the
103 callbacks on a per parser basis!
104 If you use the old callback interface through global callbacks,
106 XML::LibXML::InputCallback will treat them with a lower priority as the
107 ones registered using the new interface. The global callbacks will not
108 override the callback groups registered using the new interface. Local
109 callbacks are attached to a specific parser instance, therefore they
110 are treated with highest priority. If the match callback of the
111 callback group registered as local variable is identical to one of the
112 callback groups registered using the new interface, that callback group
113 will be replaced.
114 Users of the old callback implementation whose open callback returned a
116 plain string, will have to adapt their code to return a reference to
117 that string after upgrading to version >= 1.59. The new callback system
118 can only deal with the open callback returning a reference!
119
121 Global Variables
122 $_CUR_CB
123 Stores the current callback and can be used as shortcut to access
124 the callback stack.
125 @_GLOBAL_CALLBACKS
127 Stores all callback groups for the current parser process.
128 @_CB_STACK
130 Stores the currently used callback group. Used to prevent parser
131 errors when dealing with nested XML data.
132 Global Callbacks
134 _callback_match
135 Implements the interface for the match callback at C-level and for
136 the selection of the callback group from the callbacks defined at
137 the Perl-level.
138 _callback_open
140 Forwards the open callback from libxml2 to the corresponding
141 callback function at the Perl-level.
142 _callback_read
144 Forwards the read request to the corresponding callback function at
145 the Perl-level and returns the result to libxml2.
146 _callback_close
148 Forwards the close callback from libxml2 to the corresponding
149 callback function at the Perl-level..
150 Class methods
152 new()
153 A simple constructor.
154 register_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])
156 The four callbacks have to be given as array reference in the above
157 order match, open, read, close!
158 unregister_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])
160 With no arguments given, "unregister_callbacks()" will delete the
161 last registered callback group from the stack. If four callbacks
162 are passed as array reference, the callback group to unregister
163 will be identified by the match callback and deleted from the
164 callback stack. Note that if several identical match callbacks are
165 defined in different callback groups, ALL of them will be deleted
166 from the stack.
167 init_callbacks()
169 Initializes the callback system before a parsing process.
170 cleanup_callbacks()
172 Resets global variables and the libxml2 callback stack.
173 lib_init_callbacks()
175 Used internally for callback registration at C-level.
176 lib_cleanup_callbacks()
178 Used internally for callback resetting at the C-level.
179
181 The following example is a purely fictitious example that uses a
182 MyScheme::Handler object that responds to methods similar to an
183 IO::Handle.
184 # Define the four callback functions
186 sub match_uri {
187 my $uri = shift;
188 return $uri =~ /^myscheme:/; # trigger our callback group at a 'myscheme' URIs
189 }
190 sub open_uri {
192 my $uri = shift;
193 my $handler = MyScheme::Handler->new($uri);
194 return $handler;
195 }
196 # The returned $buffer will be parsed by the libxml2 parser
198 sub read_uri {
199 my $handler = shift;
200 my $length = shift;
201 my $buffer;
202 read($handler, $buffer, $length);
203 return $buffer; # $buffer will be an empty string '' if read() is done
204 }
205 # Close the handle associated with the resource.
207 sub close_uri {
208 my $handler = shift;
209 close($handler);
210 }
211 # Register them with a instance of XML::LibXML::InputCallback
213 my $input_callbacks = XML::LibXML::InputCallback->new();
214 $input_callbacks->register_callbacks([ \&match_uri, \&open_uri,
215 \&read_uri, \&close_uri ] );
216 # Register the callback group at a parser instance
218 $parser->input_callbacks( $input_callbacks );
219 # $some_xml_file will be parsed using our callbacks
221 $parser->parse_file( $some_xml_file );
222
224 Matt Sergeant, Christian Glahn, Petr Pajas
225
227 1.70
228
230 2001-2007, AxKit.com Ltd.
231 2002-2006, Christian Glahn.
233 2006-2009, Petr Pajas.
235perl v5.12.0 2009-10-07 XML::LibXML::InputCallback(3)