diff options
author | Norbert Preining <preining@logic.at> | 2010-03-01 01:54:19 +0000 |
---|---|---|
committer | Norbert Preining <preining@logic.at> | 2010-03-01 01:54:19 +0000 |
commit | 904fd0757fe037dbfbf156b31f72e5ff5c7cd796 (patch) | |
tree | 36f000ab754854574aad17c01d9cd9ac739f1053 /Master/tlpkg/tlperl.straw/lib/XML/LibXML.pod | |
parent | 402bd194f686177d2dfca24f7c4766434c514141 (diff) |
commit more files of the tlperl.straw dir, still not complete
git-svn-id: svn://tug.org/texlive/trunk@17244 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/tlperl.straw/lib/XML/LibXML.pod')
-rwxr-xr-x | Master/tlpkg/tlperl.straw/lib/XML/LibXML.pod | 515 |
1 files changed, 515 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl.straw/lib/XML/LibXML.pod b/Master/tlpkg/tlperl.straw/lib/XML/LibXML.pod new file mode 100755 index 00000000000..73bf58b69f5 --- /dev/null +++ b/Master/tlpkg/tlperl.straw/lib/XML/LibXML.pod @@ -0,0 +1,515 @@ +=head1 NAME + +XML::LibXML - Perl Binding for libxml2 + +=head1 SYNOPSIS + + + + use XML::LibXML; + my $dom = XML::LibXML->load_xml(string => <<'EOT'); + <some-xml/> + EOT + + $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION; + $Version_ID = XML::LibXML::LIBXML_VERSION; + $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION; + $libxmlnode = XML::LibXML->import_GDOME( $node, $deep ); + $gdomenode = XML::LibXML->export_GDOME( $node, $deep ); + +=head1 DESCRIPTION + +This module is an interface to libxml2, providing XML and HTML parsers with +DOM, SAX and XMLReader interfaces, a large subset of DOM Layer 3 interface and +a XML::XPath-like interface to XPath API of libxml2. The module is split into +several packages which are not described in this section; unless stated +otherwise, you only need to C<<<<<< use XML::LibXML; >>>>>> in your programs. + +For further information, please check the following documentation: + +=over 4 + +=item L<<<<<< XML::LibXML::Parser >>>>>> + +Parsing XML files with XML::LibXML + + +=item L<<<<<< XML::LibXML::DOM >>>>>> + +XML::LibXML Document Object Model (DOM) Implementation + + +=item L<<<<<< XML::LibXML::SAX >>>>>> + +XML::LibXML direct SAX parser + + +=item L<<<<<< XML::LibXML::Reader >>>>>> + +Reading XML with a pull-parser + + +=item L<<<<<< XML::LibXML::Dtd >>>>>> + +XML::LibXML frontend for DTD validation + + +=item L<<<<<< XML::LibXML::RelaxNG >>>>>> + +XML::LibXML frontend for RelaxNG schema validation + + +=item L<<<<<< XML::LibXML::Schema >>>>>> + +XML::LibXML frontend for W3C Schema schema validation + + +=item L<<<<<< XML::LibXML::XPathContext >>>>>> + +API for evaluating XPath expressions with enhanced support for the evaluation +context + + +=item L<<<<<< XML::LibXML::InputCallback >>>>>> + +Implementing custom URI Resolver and input callbacks + + +=item L<<<<<< XML::LibXML::Common >>>>>> + +Common functions for XML::LibXML related Classes + + + +=back + +The nodes in the Document Object Model (DOM) are represented by the following +classes (most of which "inherit" from L<<<<<< XML::LibXML::Node >>>>>>): + +=over 4 + +=item L<<<<<< XML::LibXML::Document >>>>>> + +XML::LibXML class for DOM document nodes + + +=item L<<<<<< XML::LibXML::Node >>>>>> + +Abstract base class for XML::LibXML DOM nodes + + +=item L<<<<<< XML::LibXML::Element >>>>>> + +XML::LibXML class for DOM element nodes + + +=item L<<<<<< XML::LibXML::Text >>>>>> + +XML::LibXML class for DOM text nodes + + +=item L<<<<<< XML::LibXML::Comment >>>>>> + +XML::LibXML class for comment DOM nodes + + +=item L<<<<<< XML::LibXML::CDATASection >>>>>> + +XML::LibXML class for DOM CDATA sections + + +=item L<<<<<< XML::LibXML::Attr >>>>>> + +XML::LibXML DOM attribute class + + +=item L<<<<<< XML::LibXML::DocumentFragment >>>>>> + +XML::LibXML's DOM L2 Document Fragment implementation + + +=item L<<<<<< XML::LibXML::Namespace >>>>>> + +XML::LibXML DOM namespace nodes + + +=item L<<<<<< XML::LibXML::PI >>>>>> + +XML::LibXML DOM processing instruction nodes + + + +=back + + +=head1 ENCODINGS SUPPORT IN XML::LIBXML + +Recall that since version 5.6.1, Perl distinguishes between character strings +(internally encoded in UTF-8) and so called binary data and, accordingly, +applies either character or byte semantics to them. A scalar representing a +character string is distinguished from a byte string by special flag (UTF8). +Please refer to I<<<<<< perlunicode >>>>>> for details. + +XML::LibXML's API is designed to deal with many encodings of XML documents +completely transparently, so that the application using XML::LibXML can be +completely ignorant about the encoding of the XML documents it works with. On +the other hand, functions like C<<<<<< XML::LibXML::Document->setEncoding >>>>>> give the user control over the document encoding. + +To ensure the aforementioned transparency and uniformity, most functions of +XML::LibXML that work with in-memory trees accept and return data as character +strings (i.e. UTF-8 encoded with the UTF8 flag on) regardless of the original +document encoding; however, the functions related to I/O operations (i.e. +parsing and saving) operate with binary data (in the original document +encoding) obeying the encoding declaration of the XML documents. + +Below we summarize basic rules and principles regarding encoding: + + +=over 4 + +=item 1. + +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 +serializer of (full) XML documents. This is because the conversion of the data +to/from the internal character representation is provided by libxml2 itself +which must be able to enforce the encoding specified by the C<<<<<< <?xml version="1.0" encoding="..."?> >>>>>> declaration. Here is an example to follow: + + use XML::LibXML; + open my $fh, "file.xml"; + binmode $fh; # drop all PerlIO layers possibly created by a use open pragma + $doc = XML::LibXML->load_xml(IO => $fh); + open my $out, "out.xml"; + binmode $fh; # as above + $doc->toFh($fh); + # or + print $fh $doc->toString(); + + + + + +=item 2. + +All functions working with DOM accept and return character strings (UTF-8 +encoded with UTF8 flag on). E.g. + + my $doc = XML::LibXML:Document->new('1.0',$some_encoding); + my $element = $doc->createElement($name); + $element->appendText($text); + $xml_fragment = $element->toString(); # returns a character string + $xml_document = $doc->toString(); # returns a byte string + +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 +method C<<<<<< toString >>>>>> returns XML as a character string if applied to other node than the Document +node and a byte string containing the apropriate + + <?xml version="1.0" encoding="..."?> + +declaration if applied to a L<<<<<< XML::LibXML::Document >>>>>>. + + + +=item 3. + +DOM methods also accept binary strings in the original encoding of the document +to which the node belongs (UTF-8 is assumed if the node is not attached to any +document). Exploiting this feature is NOT RECOMMENDED since it is considered a +bad practice. + + + + my $doc = XML::LibXML:Document->new('1.0','iso-8859-2'); + my $text = $doc->createTextNode($some_latin2_encoded_byte_string); + # WORKS, BUT NOT RECOMMENDED! + + + +=back + +I<<<<<< NOTE: >>>>>> libxml2 support for many encodings is based on the iconv library. The actual +list of supported encodings may vary from platform to platform. To test if your +platform works correctly with your language encoding, build a simple document +in the particular encoding and try to parse it with XML::LibXML to see if the +parser produces any errors. Occasional crashes were reported on rare platforms +that ship with a broken version of iconv. + + +=head1 THREAD SUPPORT + +XML::LibXML since 1.67 partially supports Perl threads in Perl >= 5.8.8. +XML::LibXML can be used with threads in two ways: + +By default, all XML::LibXML classes use CLONE_SKIP class method to prevent Perl +from copying XML::LibXML::* objects when a new thread is spawn. In this mode, +all XML::LibXML::* objects are thread specific. This is the safest way to work +with XML::LibXML in threads. + +Alternatively, one may use + + + + use threads; + use XML::LibXML qw(:threads_shared); + +to indicate, that all XML::LibXML node and parser objects should be shared +between the main thread and any thread spawn from there. For example, in + + + + my $doc = XML::LibXML->load_xml(location => $filename); + my $thr = threads->new(sub{ + # code working with $doc + 1; + }); + $thr->join; + +the variable C<<<<<< $doc >>>>>> refers to the exact same XML::LibXML::Document in the spawned thread as in the +main thread. + +Without using mutex locks, oaralel threads may read the same document (i.e. any +node that belongs to the document), parse files, and modify different +documents. + +However, if there is a chance that some of the threads will attempt to modify a +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 +for creating a mutex lock and using it in I<<<<<< both >>>>>> in the thread that modifies and the thread that reads: + + + + my $doc = XML::LibXML->load_xml(location => $filename); + my $mutex : shared; + my $thr = threads->new(sub{ + lock $mutex; + my $el = $doc->createElement('foo'); + # ... + 1; + }); + { + lock $mutex; + my $root = $doc->documentElement; + say $root->name; + } + $thr->join; + +Note that libxml2 uses dictionaries to store short strings and these +dicionaries are kept on a document node. Without mutex locks, it could happen +in the previous example that the thread modifies the dictionary while other +threads attempt to read from it, which could easily lead to a crash. + + +=head1 VERSION INFORMATION + +Sometimes it is useful to figure out, for which version XML::LibXML was +compiled for. In most cases this is for debugging or to check if a given +installation meets all functionality for the package. The functions +XML::LibXML::LIBXML_DOTTED_VERSION and XML::LibXML::LIBXML_VERSION provide this +version information. Both functions simply pass through the values of the +similar named macros of libxml2. Similarly, XML::LibXML::LIBXML_RUNTIME_VERSION +returns the version of the (usually dynamically) linked libxml2. + +=over 4 + +=item XML::LibXML::LIBXML_DOTTED_VERSION + + $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION; + +Returns the version string of the libxml2 version XML::LibXML was compiled for. +This will be "2.6.2" for "libxml2 2.6.2". + + +=item XML::LibXML::LIBXML_VERSION + + $Version_ID = XML::LibXML::LIBXML_VERSION; + +Returns the version id of the libxml2 version XML::LibXML was compiled for. +This will be "20602" for "libxml2 2.6.2". Don't mix this version id with +$XML::LibXML::VERSION. The latter contains the version of XML::LibXML itself +while the first contains the version of libxml2 XML::LibXML was compiled for. + + +=item XML::LibXML::LIBXML_RUNTIME_VERSION + + $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION; + +Returns a version string of the libxml2 which is (usually dynamically) linked +by XML::LibXML. This will be "20602" for libxml2 released as "2.6.2" and +something like "20602-CVS2032" for a CVS build of libxml2. + +XML::LibXML issues a warning if the version of libxml2 dynamically linked to it +is less than the version of libxml2 which it was compiled against. + + + +=back + + +=head1 EXPORTS + +By default the module exports all constants and functions listed in the :all +tag, described below. + + +=head1 EXPORT TAGS + +=over 4 + +=item C<<<<<< :all >>>>>> + +Includes the tags C<<<<<< :libxml >>>>>>, C<<<<<< :encoding >>>>>>, and C<<<<<< :ns >>>>>> described below. + + +=item C<<<<<< :libxml >>>>>> + +Exports integer constants for DOM node types. + + + + XML_ELEMENT_NODE => 1 + XML_ATTRIBUTE_NODE => 2 + XML_TEXT_NODE => 3 + XML_CDATA_SECTION_NODE => 4 + XML_ENTITY_REF_NODE => 5 + XML_ENTITY_NODE => 6 + XML_PI_NODE => 7 + XML_COMMENT_NODE => 8 + XML_DOCUMENT_NODE => 9 + XML_DOCUMENT_TYPE_NODE => 10 + XML_DOCUMENT_FRAG_NODE => 11 + XML_NOTATION_NODE => 12 + XML_HTML_DOCUMENT_NODE => 13 + XML_DTD_NODE => 14 + XML_ELEMENT_DECL => 15 + XML_ATTRIBUTE_DECL => 16 + XML_ENTITY_DECL => 17 + XML_NAMESPACE_DECL => 18 + XML_XINCLUDE_START => 19 + XML_XINCLUDE_END => 20 + + +=item C<<<<<< :encoding >>>>>> + +Exports two encoding conversion functions from XML::LibXML::Common. + + + + encodeToUTF8() + decodeFromUTF8() + + +=item C<<<<<< :ns >>>>>> + +Exports two convenience constants: the implicit namespace of the reserved C<<<<<< xml: >>>>>> prefix, and the implicit namespace for the reserved C<<<<<< xmlns: >>>>>> prefix. + + + + XML_XML_NS => 'http://www.w3.org/XML/1998/namespace' + XML_XMLNS_NS => 'http://www.w3.org/2000/xmlns/' + + + +=back + + +=head1 RELATED MODULES + +The modules described in this section are not part of the XML::LibXML package +itself. As they support some additional features, they are mentioned here. + +=over 4 + +=item L<<<<<< XML::LibXSLT >>>>>> + +XSLT 1.0 Processor using libxslt and XML::LibXML + + +=item L<<<<<< XML::LibXML::Iterator >>>>>> + +XML::LibXML Implementation of the DOM Traversal Specification + + +=item L<<<<<< XML::CompactTree::XS >>>>>> + +Uses XML::LibXML::Reader to very efficiently to parse XML document or element +into native Perl data structures, which are less flexible but significantly +faster to process then DOM. + + + +=back + + +=head1 XML::LIBXML AND XML::GDOME + +Note: I<<<<<< THE FUNCTIONS DESCRIBED HERE ARE STILL EXPERIMENTAL >>>>>> + +Although both modules make use of libxml2's XML capabilities, the DOM +implementation of both modules are not compatible. But still it is possible to +exchange nodes from one DOM to the other. The concept of this exchange is +pretty similar to the function cloneNode(): The particular node is copied on +the low-level to the opposite DOM implementation. + +Since the DOM implementations cannot coexist within one document, one is forced +to copy each node that should be used. Because you are always keeping two nodes +this may cause quite an impact on a machines memory usage. + +XML::LibXML provides two functions to export or import GDOME nodes: +import_GDOME() and export_GDOME(). Both function have two parameters: the node +and a flag for recursive import. The flag works as in cloneNode(). + +The two functions allow to export and import XML::GDOME nodes explicitly, +however, XML::LibXML allows also the transparent import of XML::GDOME nodes in +functions such as appendChild(), insertAfter() and so on. While native nodes +are automatically adopted in most functions XML::GDOME nodes are always cloned +in advance. Thus if the original node is modified after the operation, the node +in the XML::LibXML document will not have this information. + +=over 4 + +=item import_GDOME + + $libxmlnode = XML::LibXML->import_GDOME( $node, $deep ); + +This clones an XML::GDOME node to a XML::LibXML node explicitly. + + +=item export_GDOME + + $gdomenode = XML::LibXML->export_GDOME( $node, $deep ); + +Allows to clone an XML::LibXML node into a XML::GDOME node. + + + +=back + + +=head1 CONTACTS + +For bug reports, please use the CPAN request tracker on +http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXML + +For suggestions etc., and other issues related to XML::LibXML you may use the +perl XML mailing list (C<<<<<< perl-xml@listserv.ActiveState.com >>>>>>), where most XML-related Perl modules are discussed. In case of problems you +should check the archives of that list first. Many problems are already +discussed there. You can find the list's archives and subscription options at L<<<<<< http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl-xml >>>>>>. + +=head1 AUTHORS + +Matt Sergeant, +Christian Glahn, +Petr Pajas + + +=head1 VERSION + +1.70 + +=head1 COPYRIGHT + +2001-2007, AxKit.com Ltd. + +2002-2006, Christian Glahn. + +2006-2009, Petr Pajas. + +=cut |