Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10) |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sp \" Vertical space (when we can't use .PP) |
6 | .if t .sp .5v |
7 | .if n .sp |
8 | .. |
9 | .de Vb \" Begin verbatim text |
10 | .ft CW |
11 | .nf |
12 | .ne \\$1 |
13 | .. |
14 | .de Ve \" End verbatim text |
15 | .ft R |
16 | .fi |
17 | .. |
18 | .\" Set up some character translations and predefined strings. \*(-- will |
19 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
20 | .\" double quote, and \*(R" will give a right double quote. \*(C+ will |
21 | .\" give a nicer C++. Capital omega is used to do unbreakable dashes and |
22 | .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, |
23 | .\" nothing in troff, for use with C<>. |
24 | .tr \(*W- |
25 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
26 | .ie n \{\ |
27 | . ds -- \(*W- |
28 | . ds PI pi |
29 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
30 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
31 | . ds L" "" |
32 | . ds R" "" |
33 | . ds C` "" |
34 | . ds C' "" |
35 | 'br\} |
36 | .el\{\ |
37 | . ds -- \|\(em\| |
38 | . ds PI \(*p |
39 | . ds L" `` |
40 | . ds R" '' |
41 | 'br\} |
42 | .\" |
43 | .\" Escape single quotes in literal strings from groff's Unicode transform. |
44 | .ie \n(.g .ds Aq \(aq |
45 | .el .ds Aq ' |
46 | .\" |
47 | .\" If the F register is turned on, we'll generate index entries on stderr for |
48 | .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
49 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
50 | .\" output yourself in some meaningful fashion. |
51 | .ie \nF \{\ |
52 | . de IX |
53 | . tm Index:\\$1\t\\n%\t"\\$2" |
54 | .. |
55 | . nr % 0 |
56 | . rr F |
57 | .\} |
58 | .el \{\ |
59 | . de IX |
60 | .. |
61 | .\} |
62 | .\" |
63 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
64 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
65 | . \" fudge factors for nroff and troff |
66 | .if n \{\ |
67 | . ds #H 0 |
68 | . ds #V .8m |
69 | . ds #F .3m |
70 | . ds #[ \f1 |
71 | . ds #] \fP |
72 | .\} |
73 | .if t \{\ |
74 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
75 | . ds #V .6m |
76 | . ds #F 0 |
77 | . ds #[ \& |
78 | . ds #] \& |
79 | .\} |
80 | . \" simple accents for nroff and troff |
81 | .if n \{\ |
82 | . ds ' \& |
83 | . ds ` \& |
84 | . ds ^ \& |
85 | . ds , \& |
86 | . ds ~ ~ |
87 | . ds / |
88 | .\} |
89 | .if t \{\ |
90 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
91 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
92 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
93 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
94 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
95 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
96 | .\} |
97 | . \" troff and (daisy-wheel) nroff accents |
98 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
99 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
100 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
101 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
102 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
103 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
104 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
105 | .ds ae a\h'-(\w'a'u*4/10)'e |
106 | .ds Ae A\h'-(\w'A'u*4/10)'E |
107 | . \" corrections for vroff |
108 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
109 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
110 | . \" for low resolution devices (crt and lpr) |
111 | .if \n(.H>23 .if \n(.V>19 \ |
112 | \{\ |
113 | . ds : e |
114 | . ds 8 ss |
115 | . ds o a |
116 | . ds d- d\h'-1'\(ga |
117 | . ds D- D\h'-1'\(hy |
118 | . ds th \o'bp' |
119 | . ds Th \o'LP' |
120 | . ds ae ae |
121 | . ds Ae AE |
122 | .\} |
123 | .rm #[ #] #H #V #F C |
124 | .\" ======================================================================== |
125 | .\" |
126 | .IX Title "LibXML 3" |
127 | .TH LibXML 3 "2009-10-07" "perl v5.8.7" "User Contributed Perl Documentation" |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
129 | .\" way too many mistakes in technical documents. |
130 | .if n .ad l |
131 | .nh |
132 | .SH "NAME" |
133 | XML::LibXML \- Perl Binding for libxml2 |
134 | .SH "SYNOPSIS" |
135 | .IX Header "SYNOPSIS" |
136 | .Vb 4 |
137 | \& use XML::LibXML; |
138 | \& my $dom = XML::LibXML\->load_xml(string => <<\*(AqEOT\*(Aq); |
139 | \& <some\-xml/> |
140 | \& EOT |
141 | \& |
142 | \& $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION; |
143 | \& $Version_ID = XML::LibXML::LIBXML_VERSION; |
144 | \& $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION; |
145 | \& $libxmlnode = XML::LibXML\->import_GDOME( $node, $deep ); |
146 | \& $gdomenode = XML::LibXML\->export_GDOME( $node, $deep ); |
147 | .Ve |
148 | .SH "DESCRIPTION" |
149 | .IX Header "DESCRIPTION" |
150 | This module is an interface to libxml2, providing \s-1XML\s0 and \s-1HTML\s0 parsers with |
151 | \&\s-1DOM\s0, \s-1SAX\s0 and XMLReader interfaces, a large subset of \s-1DOM\s0 Layer 3 interface and |
152 | a XML::XPath\-like interface to XPath \s-1API\s0 of libxml2. The module is split into |
153 | several packages which are not described in this section; unless stated |
154 | otherwise, you only need to \f(CW\*(C`use XML::LibXML;\*(C'\fR in your programs. |
155 | .PP |
156 | For further information, please check the following documentation: |
157 | .IP "XML::LibXML::Parser" 4 |
158 | .IX Item "XML::LibXML::Parser" |
159 | Parsing \s-1XML\s0 files with XML::LibXML |
160 | .IP "XML::LibXML::DOM" 4 |
161 | .IX Item "XML::LibXML::DOM" |
162 | XML::LibXML Document Object Model (\s-1DOM\s0) Implementation |
163 | .IP "XML::LibXML::SAX" 4 |
164 | .IX Item "XML::LibXML::SAX" |
165 | XML::LibXML direct \s-1SAX\s0 parser |
166 | .IP "XML::LibXML::Reader" 4 |
167 | .IX Item "XML::LibXML::Reader" |
168 | Reading \s-1XML\s0 with a pull-parser |
169 | .IP "XML::LibXML::Dtd" 4 |
170 | .IX Item "XML::LibXML::Dtd" |
171 | XML::LibXML frontend for \s-1DTD\s0 validation |
172 | .IP "XML::LibXML::RelaxNG" 4 |
173 | .IX Item "XML::LibXML::RelaxNG" |
174 | XML::LibXML frontend for RelaxNG schema validation |
175 | .IP "XML::LibXML::Schema" 4 |
176 | .IX Item "XML::LibXML::Schema" |
177 | XML::LibXML frontend for W3C Schema schema validation |
178 | .IP "XML::LibXML::XPathContext" 4 |
179 | .IX Item "XML::LibXML::XPathContext" |
180 | \&\s-1API\s0 for evaluating XPath expressions with enhanced support for the evaluation |
181 | context |
182 | .IP "XML::LibXML::InputCallback" 4 |
183 | .IX Item "XML::LibXML::InputCallback" |
184 | Implementing custom \s-1URI\s0 Resolver and input callbacks |
185 | .IP "XML::LibXML::Common" 4 |
186 | .IX Item "XML::LibXML::Common" |
187 | Common functions for XML::LibXML related Classes |
188 | .PP |
189 | The nodes in the Document Object Model (\s-1DOM\s0) are represented by the following |
190 | classes (most of which \*(L"inherit\*(R" from XML::LibXML::Node): |
191 | .IP "XML::LibXML::Document" 4 |
192 | .IX Item "XML::LibXML::Document" |
193 | XML::LibXML class for \s-1DOM\s0 document nodes |
194 | .IP "XML::LibXML::Node" 4 |
195 | .IX Item "XML::LibXML::Node" |
196 | Abstract base class for XML::LibXML \s-1DOM\s0 nodes |
197 | .IP "XML::LibXML::Element" 4 |
198 | .IX Item "XML::LibXML::Element" |
199 | XML::LibXML class for \s-1DOM\s0 element nodes |
200 | .IP "XML::LibXML::Text" 4 |
201 | .IX Item "XML::LibXML::Text" |
202 | XML::LibXML class for \s-1DOM\s0 text nodes |
203 | .IP "XML::LibXML::Comment" 4 |
204 | .IX Item "XML::LibXML::Comment" |
205 | XML::LibXML class for comment \s-1DOM\s0 nodes |
206 | .IP "XML::LibXML::CDATASection" 4 |
207 | .IX Item "XML::LibXML::CDATASection" |
208 | XML::LibXML class for \s-1DOM\s0 \s-1CDATA\s0 sections |
209 | .IP "XML::LibXML::Attr" 4 |
210 | .IX Item "XML::LibXML::Attr" |
211 | XML::LibXML \s-1DOM\s0 attribute class |
212 | .IP "XML::LibXML::DocumentFragment" 4 |
213 | .IX Item "XML::LibXML::DocumentFragment" |
214 | XML::LibXML's \s-1DOM\s0 L2 Document Fragment implementation |
215 | .IP "XML::LibXML::Namespace" 4 |
216 | .IX Item "XML::LibXML::Namespace" |
217 | XML::LibXML \s-1DOM\s0 namespace nodes |
218 | .IP "XML::LibXML::PI" 4 |
219 | .IX Item "XML::LibXML::PI" |
220 | XML::LibXML \s-1DOM\s0 processing instruction nodes |
221 | .SH "ENCODINGS SUPPORT IN XML::LIBXML" |
222 | .IX Header "ENCODINGS SUPPORT IN XML::LIBXML" |
223 | Recall that since version 5.6.1, Perl distinguishes between character strings |
224 | (internally encoded in \s-1UTF\-8\s0) and so called binary data and, accordingly, |
225 | applies either character or byte semantics to them. A scalar representing a |
226 | character string is distinguished from a byte string by special flag (\s-1UTF8\s0). |
227 | Please refer to \fIperlunicode\fR for details. |
228 | .PP |
229 | XML::LibXML's \s-1API\s0 is designed to deal with many encodings of \s-1XML\s0 documents |
230 | completely transparently, so that the application using XML::LibXML can be |
231 | completely ignorant about the encoding of the \s-1XML\s0 documents it works with. On |
232 | the other hand, functions like \f(CW\*(C`XML::LibXML::Document\->setEncoding\*(C'\fR give the user control over the document encoding. |
233 | .PP |
234 | To ensure the aforementioned transparency and uniformity, most functions of |
235 | XML::LibXML that work with in-memory trees accept and return data as character |
236 | strings (i.e. \s-1UTF\-8\s0 encoded with the \s-1UTF8\s0 flag on) regardless of the original |
237 | document encoding; however, the functions related to I/O operations (i.e. |
238 | parsing and saving) operate with binary data (in the original document |
239 | encoding) obeying the encoding declaration of the \s-1XML\s0 documents. |
240 | .PP |
241 | Below we summarize basic rules and principles regarding encoding: |
242 | .IP "1." 4 |
243 | Do \s-1NOT\s0 apply any encoding-related PerlIO layers (\f(CW\*(C`:utf8\*(C'\fR or \f(CW\*(C`:encoding(...)\*(C'\fR) to file handles that are an input for the parses or an output for a |
244 | serializer of (full) \s-1XML\s0 documents. This is because the conversion of the data |
245 | to/from the internal character representation is provided by libxml2 itself |
246 | which must be able to enforce the encoding specified by the \f(CW\*(C`<?xml version="1.0" encoding="..."?>\*(C'\fR declaration. Here is an example to follow: |
247 | .Sp |
248 | .Vb 9 |
249 | \& use XML::LibXML; |
250 | \& open my $fh, "file.xml"; |
251 | \& binmode $fh; # drop all PerlIO layers possibly created by a use open pragma |
252 | \& $doc = XML::LibXML\->load_xml(IO => $fh); |
253 | \& open my $out, "out.xml"; |
254 | \& binmode $fh; # as above |
255 | \& $doc\->toFh($fh); |
256 | \& # or |
257 | \& print $fh $doc\->toString(); |
258 | .Ve |
259 | .IP "2." 4 |
260 | All functions working with \s-1DOM\s0 accept and return character strings (\s-1UTF\-8\s0 |
261 | encoded with \s-1UTF8\s0 flag on). E.g. |
262 | .Sp |
263 | .Vb 5 |
264 | \& my $doc = XML::LibXML:Document\->new(\*(Aq1.0\*(Aq,$some_encoding); |
265 | \& my $element = $doc\->createElement($name); |
266 | \& $element\->appendText($text); |
267 | \& $xml_fragment = $element\->toString(); # returns a character string |
268 | \& $xml_document = $doc\->toString(); # returns a byte string |
269 | .Ve |
270 | .Sp |
271 | where \f(CW$some_encoding\fR is the document encoding that will be used when saving the document, and \f(CW$name\fR and \f(CW$text\fR contain character strings (\s-1UTF\-8\s0 encoded with \s-1UTF8\s0 flag on). Note that the |
272 | method \f(CW\*(C`toString\*(C'\fR returns \s-1XML\s0 as a character string if applied to other node than the Document |
273 | node and a byte string containing the apropriate |
274 | .Sp |
275 | .Vb 1 |
276 | \& <?xml version="1.0" encoding="..."?> |
277 | .Ve |
278 | .Sp |
279 | declaration if applied to a XML::LibXML::Document. |
280 | .IP "3." 4 |
281 | \&\s-1DOM\s0 methods also accept binary strings in the original encoding of the document |
282 | to which the node belongs (\s-1UTF\-8\s0 is assumed if the node is not attached to any |
283 | document). Exploiting this feature is \s-1NOT\s0 \s-1RECOMMENDED\s0 since it is considered a |
284 | bad practice. |
285 | .Sp |
286 | .Vb 3 |
287 | \& my $doc = XML::LibXML:Document\->new(\*(Aq1.0\*(Aq,\*(Aqiso\-8859\-2\*(Aq); |
288 | \& my $text = $doc\->createTextNode($some_latin2_encoded_byte_string); |
289 | \& # WORKS, BUT NOT RECOMMENDED! |
290 | .Ve |
291 | .PP |
292 | \&\fI\s-1NOTE:\s0\fR libxml2 support for many encodings is based on the iconv library. The actual |
293 | list of supported encodings may vary from platform to platform. To test if your |
294 | platform works correctly with your language encoding, build a simple document |
295 | in the particular encoding and try to parse it with XML::LibXML to see if the |
296 | parser produces any errors. Occasional crashes were reported on rare platforms |
297 | that ship with a broken version of iconv. |
298 | .SH "THREAD SUPPORT" |
299 | .IX Header "THREAD SUPPORT" |
300 | XML::LibXML since 1.67 partially supports Perl threads in Perl >= 5.8.8. |
301 | XML::LibXML can be used with threads in two ways: |
302 | .PP |
303 | By default, all XML::LibXML classes use \s-1CLONE_SKIP\s0 class method to prevent Perl |
304 | from copying XML::LibXML::* objects when a new thread is spawn. In this mode, |
305 | all XML::LibXML::* objects are thread specific. This is the safest way to work |
306 | with XML::LibXML in threads. |
307 | .PP |
308 | Alternatively, one may use |
309 | .PP |
310 | .Vb 2 |
311 | \& use threads; |
312 | \& use XML::LibXML qw(:threads_shared); |
313 | .Ve |
314 | .PP |
315 | to indicate, that all XML::LibXML node and parser objects should be shared |
316 | between the main thread and any thread spawn from there. For example, in |
317 | .PP |
318 | .Vb 6 |
319 | \& my $doc = XML::LibXML\->load_xml(location => $filename); |
320 | \& my $thr = threads\->new(sub{ |
321 | \& # code working with $doc |
322 | \& 1; |
323 | \& }); |
324 | \& $thr\->join; |
325 | .Ve |
326 | .PP |
327 | the variable \f(CW$doc\fR refers to the exact same XML::LibXML::Document in the spawned thread as in the |
328 | main thread. |
329 | .PP |
330 | Without using mutex locks, oaralel threads may read the same document (i.e. any |
331 | node that belongs to the document), parse files, and modify different |
332 | documents. |
333 | .PP |
334 | However, if there is a chance that some of the threads will attempt to modify a |
335 | document ( or even create new nodes based on that document, e.g. with \f(CW\*(C`$doc\->createElement\*(C'\fR) that other threads may be reading at the same time, the user is responsible |
336 | for creating a mutex lock and using it in \fIboth\fR in the thread that modifies and the thread that reads: |
337 | .PP |
338 | .Vb 10 |
339 | \& my $doc = XML::LibXML\->load_xml(location => $filename); |
340 | \& my $mutex : shared; |
341 | \& my $thr = threads\->new(sub{ |
342 | \& lock $mutex; |
343 | \& my $el = $doc\->createElement(\*(Aqfoo\*(Aq); |
344 | \& # ... |
345 | \& 1; |
346 | \& }); |
347 | \& { |
348 | \& lock $mutex; |
349 | \& my $root = $doc\->documentElement; |
350 | \& say $root\->name; |
351 | \& } |
352 | \& $thr\->join; |
353 | .Ve |
354 | .PP |
355 | Note that libxml2 uses dictionaries to store short strings and these |
356 | dicionaries are kept on a document node. Without mutex locks, it could happen |
357 | in the previous example that the thread modifies the dictionary while other |
358 | threads attempt to read from it, which could easily lead to a crash. |
359 | .SH "VERSION INFORMATION" |
360 | .IX Header "VERSION INFORMATION" |
361 | Sometimes it is useful to figure out, for which version XML::LibXML was |
362 | compiled for. In most cases this is for debugging or to check if a given |
363 | installation meets all functionality for the package. The functions |
364 | XML::LibXML::LIBXML_DOTTED_VERSION and XML::LibXML::LIBXML_VERSION provide this |
365 | version information. Both functions simply pass through the values of the |
366 | similar named macros of libxml2. Similarly, XML::LibXML::LIBXML_RUNTIME_VERSION |
367 | returns the version of the (usually dynamically) linked libxml2. |
368 | .IP "XML::LibXML::LIBXML_DOTTED_VERSION" 4 |
369 | .IX Item "XML::LibXML::LIBXML_DOTTED_VERSION" |
370 | .Vb 1 |
371 | \& $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION; |
372 | .Ve |
373 | .Sp |
374 | Returns the version string of the libxml2 version XML::LibXML was compiled for. |
375 | This will be \*(L"2.6.2\*(R" for \*(L"libxml2 2.6.2\*(R". |
376 | .IP "XML::LibXML::LIBXML_VERSION" 4 |
377 | .IX Item "XML::LibXML::LIBXML_VERSION" |
378 | .Vb 1 |
379 | \& $Version_ID = XML::LibXML::LIBXML_VERSION; |
380 | .Ve |
381 | .Sp |
382 | Returns the version id of the libxml2 version XML::LibXML was compiled for. |
383 | This will be \*(L"20602\*(R" for \*(L"libxml2 2.6.2\*(R". Don't mix this version id with |
384 | \&\f(CW$XML::LibXML::VERSION\fR. The latter contains the version of XML::LibXML itself |
385 | while the first contains the version of libxml2 XML::LibXML was compiled for. |
386 | .IP "XML::LibXML::LIBXML_RUNTIME_VERSION" 4 |
387 | .IX Item "XML::LibXML::LIBXML_RUNTIME_VERSION" |
388 | .Vb 1 |
389 | \& $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION; |
390 | .Ve |
391 | .Sp |
392 | Returns a version string of the libxml2 which is (usually dynamically) linked |
393 | by XML::LibXML. This will be \*(L"20602\*(R" for libxml2 released as \*(L"2.6.2\*(R" and |
394 | something like \*(L"20602\-CVS2032\*(R" for a \s-1CVS\s0 build of libxml2. |
395 | .Sp |
396 | XML::LibXML issues a warning if the version of libxml2 dynamically linked to it |
397 | is less than the version of libxml2 which it was compiled against. |
398 | .SH "EXPORTS" |
399 | .IX Header "EXPORTS" |
400 | By default the module exports all constants and functions listed in the :all |
401 | tag, described below. |
402 | .SH "EXPORT TAGS" |
403 | .IX Header "EXPORT TAGS" |
404 | .ie n .IP """:all""" 4 |
405 | .el .IP "\f(CW:all\fR" 4 |
406 | .IX Item ":all" |
407 | Includes the tags \f(CW\*(C`:libxml\*(C'\fR, \f(CW\*(C`:encoding\*(C'\fR, and \f(CW\*(C`:ns\*(C'\fR described below. |
408 | .ie n .IP """:libxml""" 4 |
409 | .el .IP "\f(CW:libxml\fR" 4 |
410 | .IX Item ":libxml" |
411 | Exports integer constants for \s-1DOM\s0 node types. |
412 | .Sp |
413 | .Vb 10 |
414 | \& XML_ELEMENT_NODE => 1 |
415 | \& XML_ATTRIBUTE_NODE => 2 |
416 | \& XML_TEXT_NODE => 3 |
417 | \& XML_CDATA_SECTION_NODE => 4 |
418 | \& XML_ENTITY_REF_NODE => 5 |
419 | \& XML_ENTITY_NODE => 6 |
420 | \& XML_PI_NODE => 7 |
421 | \& XML_COMMENT_NODE => 8 |
422 | \& XML_DOCUMENT_NODE => 9 |
423 | \& XML_DOCUMENT_TYPE_NODE => 10 |
424 | \& XML_DOCUMENT_FRAG_NODE => 11 |
425 | \& XML_NOTATION_NODE => 12 |
426 | \& XML_HTML_DOCUMENT_NODE => 13 |
427 | \& XML_DTD_NODE => 14 |
428 | \& XML_ELEMENT_DECL => 15 |
429 | \& XML_ATTRIBUTE_DECL => 16 |
430 | \& XML_ENTITY_DECL => 17 |
431 | \& XML_NAMESPACE_DECL => 18 |
432 | \& XML_XINCLUDE_START => 19 |
433 | \& XML_XINCLUDE_END => 20 |
434 | .Ve |
435 | .ie n .IP """:encoding""" 4 |
436 | .el .IP "\f(CW:encoding\fR" 4 |
437 | .IX Item ":encoding" |
438 | Exports two encoding conversion functions from XML::LibXML::Common. |
439 | .Sp |
440 | .Vb 2 |
441 | \& encodeToUTF8() |
442 | \& decodeFromUTF8() |
443 | .Ve |
444 | .ie n .IP """:ns""" 4 |
445 | .el .IP "\f(CW:ns\fR" 4 |
446 | .IX Item ":ns" |
447 | Exports two convenience constants: the implicit namespace of the reserved \f(CW\*(C`xml:\*(C'\fR prefix, and the implicit namespace for the reserved \f(CW\*(C`xmlns:\*(C'\fR prefix. |
448 | .Sp |
449 | .Vb 2 |
450 | \& XML_XML_NS => \*(Aqhttp://www.w3.org/XML/1998/namespace\*(Aq |
451 | \& XML_XMLNS_NS => \*(Aqhttp://www.w3.org/2000/xmlns/\*(Aq |
452 | .Ve |
453 | .SH "RELATED MODULES" |
454 | .IX Header "RELATED MODULES" |
455 | The modules described in this section are not part of the XML::LibXML package |
456 | itself. As they support some additional features, they are mentioned here. |
457 | .IP "XML::LibXSLT" 4 |
458 | .IX Item "XML::LibXSLT" |
459 | \&\s-1XSLT\s0 1.0 Processor using libxslt and XML::LibXML |
460 | .IP "XML::LibXML::Iterator" 4 |
461 | .IX Item "XML::LibXML::Iterator" |
462 | XML::LibXML Implementation of the \s-1DOM\s0 Traversal Specification |
463 | .IP "XML::CompactTree::XS" 4 |
464 | .IX Item "XML::CompactTree::XS" |
465 | Uses XML::LibXML::Reader to very efficiently to parse \s-1XML\s0 document or element |
466 | into native Perl data structures, which are less flexible but significantly |
467 | faster to process then \s-1DOM\s0. |
468 | .SH "XML::LIBXML AND XML::GDOME" |
469 | .IX Header "XML::LIBXML AND XML::GDOME" |
470 | Note: \fI\s-1THE\s0 \s-1FUNCTIONS\s0 \s-1DESCRIBED\s0 \s-1HERE\s0 \s-1ARE\s0 \s-1STILL\s0 \s-1EXPERIMENTAL\s0\fR |
471 | .PP |
472 | Although both modules make use of libxml2's \s-1XML\s0 capabilities, the \s-1DOM\s0 |
473 | implementation of both modules are not compatible. But still it is possible to |
474 | exchange nodes from one \s-1DOM\s0 to the other. The concept of this exchange is |
475 | pretty similar to the function \fIcloneNode()\fR: The particular node is copied on |
476 | the low-level to the opposite \s-1DOM\s0 implementation. |
477 | .PP |
478 | Since the \s-1DOM\s0 implementations cannot coexist within one document, one is forced |
479 | to copy each node that should be used. Because you are always keeping two nodes |
480 | this may cause quite an impact on a machines memory usage. |
481 | .PP |
482 | XML::LibXML provides two functions to export or import \s-1GDOME\s0 nodes: |
483 | \&\fIimport_GDOME()\fR and \fIexport_GDOME()\fR. Both function have two parameters: the node |
484 | and a flag for recursive import. The flag works as in \fIcloneNode()\fR. |
485 | .PP |
486 | The two functions allow to export and import \s-1XML::GDOME\s0 nodes explicitly, |
487 | however, XML::LibXML allows also the transparent import of \s-1XML::GDOME\s0 nodes in |
488 | functions such as \fIappendChild()\fR, \fIinsertAfter()\fR and so on. While native nodes |
489 | are automatically adopted in most functions \s-1XML::GDOME\s0 nodes are always cloned |
490 | in advance. Thus if the original node is modified after the operation, the node |
491 | in the XML::LibXML document will not have this information. |
492 | .IP "import_GDOME" 4 |
493 | .IX Item "import_GDOME" |
494 | .Vb 1 |
495 | \& $libxmlnode = XML::LibXML\->import_GDOME( $node, $deep ); |
496 | .Ve |
497 | .Sp |
498 | This clones an \s-1XML::GDOME\s0 node to a XML::LibXML node explicitly. |
499 | .IP "export_GDOME" 4 |
500 | .IX Item "export_GDOME" |
501 | .Vb 1 |
502 | \& $gdomenode = XML::LibXML\->export_GDOME( $node, $deep ); |
503 | .Ve |
504 | .Sp |
505 | Allows to clone an XML::LibXML node into a \s-1XML::GDOME\s0 node. |
506 | .SH "CONTACTS" |
507 | .IX Header "CONTACTS" |
508 | For bug reports, please use the \s-1CPAN\s0 request tracker on |
509 | http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML\-LibXML |
510 | .PP |
511 | For suggestions etc., and other issues related to XML::LibXML you may use the |
512 | perl \s-1XML\s0 mailing list (\f(CW\*(C`perl\-xml@listserv.ActiveState.com\*(C'\fR), where most XML-related Perl modules are discussed. In case of problems you |
513 | should check the archives of that list first. Many problems are already |
514 | discussed there. You can find the list's archives and subscription options at <http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl\-xml>. |
515 | .SH "AUTHORS" |
516 | .IX Header "AUTHORS" |
517 | Matt Sergeant, |
518 | Christian Glahn, |
519 | Petr Pajas |
520 | .SH "VERSION" |
521 | .IX Header "VERSION" |
522 | 1.70 |
523 | .SH "COPYRIGHT" |
524 | .IX Header "COPYRIGHT" |
525 | 2001\-2007, AxKit.com Ltd. |
526 | .PP |
527 | 2002\-2006, Christian Glahn. |
528 | .PP |
529 | 2006\-2009, Petr Pajas. |