1XML::LibXML::Reader(3)User Contributed Perl DocumentationXML::LibXML::Reader(3)
2
6 XML::LibXML::Reader - XML::LibXML::Reader - interface to libxml2 pull
7 parser
8
10 use XML::LibXML::Reader;
11 my $reader = XML::LibXML::Reader->new(location => "file.xml")
15 or die "cannot read file.xml\n";
16 while ($reader->read) {
17 processNode($reader);
18 }
19 sub processNode {
23 my $reader = shift;
24 printf "%d %d %s %d\n", ($reader->depth,
25 $reader->nodeType,
26 $reader->name,
27 $reader->isEmptyElement);
28 }
29 or
31 my $reader = XML::LibXML::Reader->new(location => "file.xml")
33 or die "cannot read file.xml\n";
34 $reader->preservePattern('//table/tr');
35 $reader->finish;
36 print $reader->document->toString(1);
37
39 This is a perl interface to libxml2's pull-parser implementation
40 xmlTextReader http://xmlsoft.org/html/libxml-xmlreader.html. This
41 feature requires at least libxml2-2.6.21. Pull-parsers (such as StAX in
42 Java, or XmlReader in C#) use an iterator approach to parse XML
43 documents. They are easier to program than event-based parser (SAX) and
44 much more lightweight than tree-based parser (DOM), which load the
45 complete tree into memory.
46 The Reader acts as a cursor going forward on the document stream and
48 stopping at each node on the way. At every point, the DOM-like methods
49 of the Reader object allow one to examine the current node (name,
50 namespace, attributes, etc.)
51 The user's code keeps control of the progress and simply calls the
53 read() function repeatedly to progress to the next node in the document
54 order. Other functions provide means for skipping complete sub-trees,
55 or nodes until a specific element, etc.
56 At every time, only a very limited portion of the document is kept in
58 the memory, which makes the API more memory-efficient than using DOM.
59 However, it is also possible to mix Reader with DOM. At every point the
60 user may copy the current node (optionally expanded into a complete
61 sub-tree) from the processed document to another DOM tree, or to
62 instruct the Reader to collect sub-document in form of a DOM tree
63 consisting of selected nodes.
64 Reader API also supports namespaces, xml:base, entity handling, and DTD
66 validation. Schema and RelaxNG validation support will probably be
67 added in some later revision of the Perl interface.
68 The naming of methods compared to libxml2 and C# XmlTextReader has been
70 changed slightly to match the conventions of XML::LibXML. Some
71 functions have been changed or added with respect to the C interface.
72
74 Depending on the XML source, the Reader object can be created with
75 either of:
76 my $reader = XML::LibXML::Reader->new( location => "file.xml", ... );
78 my $reader = XML::LibXML::Reader->new( string => $xml_string, ... );
79 my $reader = XML::LibXML::Reader->new( IO => $file_handle, ... );
80 my $reader = XML::LibXML::Reader->new( FD => fileno(STDIN), ... );
81 my $reader = XML::LibXML::Reader->new( DOM => $dom, ... );
82 where ... are (optional) reader options described below in "Reader
84 options" or various parser options described in XML::LibXML::Parser.
85 The constructor recognizes the following XML sources:
86 Source specification
88 location
89 Read XML from a local file or (non-HTTPS) URL.
90 string
92 Read XML from a string.
93 IO Read XML a Perl IO filehandle.
95 FD Read XML from a file descriptor (bypasses Perl I/O layer, only
97 applicable to filehandles for regular files or pipes). Possibly
98 faster than IO.
99 DOM Use reader API to walk through a pre-parsed XML::LibXML::Document.
101 Reader options
103 encoding => $encoding
104 override document encoding.
105 RelaxNG => $rng_schema
107 can be used to pass either a XML::LibXML::RelaxNG object or a
108 filename or (non-HTTPS) URL of a RelaxNG schema to the constructor.
109 The schema is then used to validate the document as it is
110 processed.
111 Schema => $xsd_schema
113 can be used to pass either a XML::LibXML::Schema object or a
114 filename or (non-HTTPS) URL of a W3C XSD schema to the constructor.
115 The schema is then used to validate the document as it is
116 processed.
117 ... the reader further supports various parser options described in
119 XML::LibXML::Parser (specifically those labeled by /reader/).
120
122 read ()
123 Moves the position to the next node in the stream, exposing its
124 properties.
125 Returns 1 if the node was read successfully, 0 if there is no more
127 nodes to read, or -1 in case of error
128 readAttributeValue ()
130 Parses an attribute value into one or more Text and EntityReference
131 nodes.
132 Returns 1 in case of success, 0 if the reader was not positioned on
134 an attribute node or all the attribute values have been read, or -1
135 in case of error.
136 readState ()
138 Gets the read state of the reader. Returns the state value, or -1
139 in case of error. The module exports constants for the Reader
140 states, see STATES below.
141 depth ()
143 The depth of the node in the tree, starts at 0 for the root node.
144 next ()
146 Skip to the node following the current one in the document order
147 while avoiding the sub-tree if any. Returns 1 if the node was read
148 successfully, 0 if there is no more nodes to read, or -1 in case of
149 error.
150 nextElement (localname?,nsURI?)
152 Skip nodes following the current one in the document order until a
153 specific element is reached. The element's name must be equal to a
154 given localname if defined, and its namespace must equal to a given
155 nsURI if defined. Either of the arguments can be undefined (or
156 omitted, in case of the latter or both).
157 Returns 1 if the element was found, 0 if there is no more nodes to
159 read, or -1 in case of error.
160 nextPatternMatch (compiled_pattern)
162 Skip nodes following the current one in the document order until an
163 element matching a given compiled pattern is reached. See
164 XML::LibXML::Pattern for information on compiled patterns. See also
165 the "matchesPattern" method.
166 Returns 1 if the element was found, 0 if there is no more nodes to
168 read, or -1 in case of error.
169 skipSiblings ()
171 Skip all nodes on the same or lower level until the first node on a
172 higher level is reached. In particular, if the current node occurs
173 in an element, the reader stops at the end tag of the parent
174 element, otherwise it stops at a node immediately following the
175 parent node.
176 Returns 1 if successful, 0 if end of the document is reached, or -1
178 in case of error.
179 nextSibling ()
181 It skips to the node following the current one in the document
182 order while avoiding the sub-tree if any.
183 Returns 1 if the node was read successfully, 0 if there is no more
185 nodes to read, or -1 in case of error
186 nextSiblingElement (name?,nsURI?)
188 Like nextElement but only processes sibling elements of the current
189 node (moving forward using "nextSibling ()" rather than "read ()",
190 internally).
191 Returns 1 if the element was found, 0 if there is no more sibling
193 nodes, or -1 in case of error.
194 finish ()
196 Skip all remaining nodes in the document, reaching end of the
197 document.
198 Returns 1 if successful, 0 in case of error.
200 close ()
202 This method releases any resources allocated by the current
203 instance and closes any underlying input. It returns 0 on failure
204 and 1 on success. This method is automatically called by the
205 destructor when the reader is forgotten, therefore you do not have
206 to call it directly.
207
209 name ()
210 Returns the qualified name of the current node, equal to
211 (Prefix:)LocalName.
212 nodeType ()
214 Returns the type of the current node. See NODE TYPES below.
215 localName ()
217 Returns the local name of the node.
218 prefix ()
220 Returns the prefix of the namespace associated with the node.
221 namespaceURI ()
223 Returns the URI defining the namespace associated with the node.
224 isEmptyElement ()
226 Check if the current node is empty, this is a bit bizarre in the
227 sense that <a/> will be considered empty while <a></a> will not.
228 hasValue ()
230 Returns true if the node can have a text value.
231 value ()
233 Provides the text value of the node if present or undef if not
234 available.
235 readInnerXml ()
237 Reads the contents of the current node, including child nodes and
238 markup. Returns a string containing the XML of the node's content,
239 or undef if the current node is neither an element nor attribute,
240 or has no child nodes.
241 readOuterXml ()
243 Reads the contents of the current node, including child nodes and
244 markup.
245 Returns a string containing the XML of the node including its
247 content, or undef if the current node is neither an element nor
248 attribute.
249 nodePath()
251 Returns a canonical location path to the current element from the
252 root node to the current node. Namespaced elements are matched by
253 '*', because there is no way to declare prefixes within XPath
254 patterns. Unlike XML::LibXML::Node::nodePath(), this function does
255 not provide sibling counts (i.e. instead of e.g. '/a/b[1]' and
256 '/a/b[2]' you get '/a/b' for both matches).
257 matchesPattern(compiled_pattern)
259 Returns a true value if the current node matches a compiled
260 pattern. See XML::LibXML::Pattern for information on compiled
261 patterns. See also the "nextPatternMatch" method.
262
264 document ()
265 Provides access to the document tree built by the reader. This
266 function can be used to collect the preserved nodes (see
267 preserveNode() and preservePattern).
268 CAUTION: Never use this function to modify the tree unless reading
270 of the whole document is completed!
271 copyCurrentNode (deep)
273 This function is similar a DOM function copyNode(). It returns a
274 copy of the currently processed node as a corresponding DOM object.
275 Use deep = 1 to obtain the full sub-tree.
276 preserveNode ()
278 This tells the XML Reader to preserve the current node in the
279 document tree. A document tree consisting of the preserved nodes
280 and their content can be obtained using the method document() once
281 parsing is finished.
282 Returns the node or NULL in case of error.
284 preservePattern (pattern,\%ns_map)
286 This tells the XML Reader to preserve all nodes matched by the
287 pattern (which is a streaming XPath subset). A document tree
288 consisting of the preserved nodes and their content can be obtained
289 using the method document() once parsing is finished.
290 An optional second argument can be used to provide a HASH reference
292 mapping prefixes used by the XPath to namespace URIs.
293 The XPath subset available with this function is described at
295 http://www.w3.org/TR/xmlschema-1/#Selector
297 and matches the production
299 Path ::= ('.//')? ( Step '/' )* ( Step | '@' NameTest )
301 Returns a positive number in case of success and -1 in case of
303 error
304
306 attributeCount ()
307 Provides the number of attributes of the current node.
308 hasAttributes ()
310 Whether the node has attributes.
311 getAttribute (name)
313 Provides the value of the attribute with the specified qualified
314 name.
315 Returns a string containing the value of the specified attribute,
317 or undef in case of error.
318 getAttributeNs (localName, namespaceURI)
320 Provides the value of the specified attribute.
321 Returns a string containing the value of the specified attribute,
323 or undef in case of error.
324 getAttributeNo (no)
326 Provides the value of the attribute with the specified index
327 relative to the containing element.
328 Returns a string containing the value of the specified attribute,
330 or undef in case of error.
331 isDefault ()
333 Returns true if the current attribute node was generated from the
334 default value defined in the DTD.
335 moveToAttribute (name)
337 Moves the position to the attribute with the specified local name
338 and namespace URI.
339 Returns 1 in case of success, -1 in case of error, 0 if not found
341 moveToAttributeNo (no)
343 Moves the position to the attribute with the specified index
344 relative to the containing element.
345 Returns 1 in case of success, -1 in case of error, 0 if not found
347 moveToAttributeNs (localName,namespaceURI)
349 Moves the position to the attribute with the specified local name
350 and namespace URI.
351 Returns 1 in case of success, -1 in case of error, 0 if not found
353 moveToFirstAttribute ()
355 Moves the position to the first attribute associated with the
356 current node.
357 Returns 1 in case of success, -1 in case of error, 0 if not found
359 moveToNextAttribute ()
361 Moves the position to the next attribute associated with the
362 current node.
363 Returns 1 in case of success, -1 in case of error, 0 if not found
365 moveToElement ()
367 Moves the position to the node that contains the current attribute
368 node.
369 Returns 1 in case of success, -1 in case of error, 0 if not moved
371 isNamespaceDecl ()
373 Determine whether the current node is a namespace declaration
374 rather than a regular attribute.
375 Returns 1 if the current node is a namespace declaration, 0 if it
377 is a regular attribute or other type of node, or -1 in case of
378 error.
379
381 lookupNamespace (prefix)
382 Resolves a namespace prefix in the scope of the current element.
383 Returns a string containing the namespace URI to which the prefix
385 maps or undef in case of error.
386 encoding ()
388 Returns a string containing the encoding of the document or undef
389 in case of error.
390 standalone ()
392 Determine the standalone status of the document being read. Returns
393 1 if the document was declared to be standalone, 0 if it was
394 declared to be not standalone, or -1 if the document did not
395 specify its standalone status or in case of error.
396 xmlVersion ()
398 Determine the XML version of the document being read. Returns a
399 string containing the XML version of the document or undef in case
400 of error.
401 baseURI ()
403 Returns the base URI of a given node.
404 isValid ()
406 Retrieve the validity status from the parser.
407 Returns 1 if valid, 0 if no, and -1 in case of error.
409 xmlLang ()
411 The xml:lang scope within which the node resides.
412 lineNumber ()
414 Provide the line number of the current parsing point.
415 columnNumber ()
417 Provide the column number of the current parsing point.
418 byteConsumed ()
420 This function provides the current index of the parser relative to
421 the start of the current entity. This function is computed in bytes
422 from the beginning starting at zero and finishing at the size in
423 bytes of the file if parsing a file. The function is of constant
424 cost if the input is UTF-8 but can be costly if run on non-UTF-8
425 input.
426 setParserProp (prop => value, ...)
428 Change the parser processing behaviour by changing some of its
429 internal properties. The following properties are available with
430 this function: ``load_ext_dtd'', ``complete_attributes'',
431 ``validation'', ``expand_entities''.
432 Since some of the properties can only be changed before any read
434 has been done, it is best to set the parsing properties at the
435 constructor.
436 Returns 0 if the call was successful, or -1 in case of error
438 getParserProp (prop)
440 Get value of an parser internal property. The following property
441 names can be used: ``load_ext_dtd'', ``complete_attributes'',
442 ``validation'', ``expand_entities''.
443 Returns the value, usually 0 or 1, or -1 in case of error.
445
447 XML::LibXML takes care of the reader object destruction when the last
448 reference to the reader object goes out of scope. The document tree is
449 preserved, though, if either of $reader->document or
450 $reader->preserveNode was used and references to the document tree
451 exist.
452
454 The reader interface provides the following constants for node types
455 (the constant symbols are exported by default or if tag ":types" is
456 used).
457 XML_READER_TYPE_NONE => 0
459 XML_READER_TYPE_ELEMENT => 1
460 XML_READER_TYPE_ATTRIBUTE => 2
461 XML_READER_TYPE_TEXT => 3
462 XML_READER_TYPE_CDATA => 4
463 XML_READER_TYPE_ENTITY_REFERENCE => 5
464 XML_READER_TYPE_ENTITY => 6
465 XML_READER_TYPE_PROCESSING_INSTRUCTION => 7
466 XML_READER_TYPE_COMMENT => 8
467 XML_READER_TYPE_DOCUMENT => 9
468 XML_READER_TYPE_DOCUMENT_TYPE => 10
469 XML_READER_TYPE_DOCUMENT_FRAGMENT => 11
470 XML_READER_TYPE_NOTATION => 12
471 XML_READER_TYPE_WHITESPACE => 13
472 XML_READER_TYPE_SIGNIFICANT_WHITESPACE => 14
473 XML_READER_TYPE_END_ELEMENT => 15
474 XML_READER_TYPE_END_ENTITY => 16
475 XML_READER_TYPE_XML_DECLARATION => 17
476
478 The following constants represent the values returned by readState().
479 They are exported by default, or if tag ":states" is used:
480 XML_READER_NONE => -1
482 XML_READER_START => 0
483 XML_READER_ELEMENT => 1
484 XML_READER_END => 2
485 XML_READER_EMPTY => 3
486 XML_READER_BACKTRACK => 4
487 XML_READER_DONE => 5
488 XML_READER_ERROR => 6
489
491 XML::LibXML::Pattern for information about compiled patterns.
492 http://xmlsoft.org/html/libxml-xmlreader.html
494 http://dotgnu.org/pnetlib-doc/System/Xml/XmlTextReader.html
496
498 Heiko Klein, <H.Klein@gmx.net<gt> and Petr Pajas
499
501 Matt Sergeant, Christian Glahn, Petr Pajas
502
504 2.0208
505
507 2001-2007, AxKit.com Ltd.
508 2002-2006, Christian Glahn.
510 2006-2009, Petr Pajas.
512
514 This program is free software; you can redistribute it and/or modify it
515 under the same terms as Perl itself.
516perl v5.36.0 2023-01-20 XML::LibXML::Reader(3)