local-lib5/man/man3/XML::LibXML.3pm

   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.