local-lib5/lib/perl5/i486-linux-gnu-thread-multi/XML/LibXML.pod

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