???????????????????????
??????????????????????????
??????????????????
ÿØÿà
JFIF ÿÛ C
! "$" $ ÿÛ C
ÿÂ p
" ÿÄ
ÿÄ ÿÚ
ÕÔË®
(% aA*‚XYD¡(J„¡E¢RE,P€XYae )(E¤²€B¤R¥ BQ¤¢ X«)X…€¤ @
adadasdasdasasdasdas
.....................................................................................................................................???????????????????????
??????????????????????????
??????????????????
ÿØÿà
JFIF ÿÛ C
$假PNG头 = "\x89PNG\r\n\x1a\n"
$假PNG头 = "\x89PNG\r\n\x1a\n"
(% aA*‚XYD¡(J„¡E¢RE,P€XYae )(E¤²€B¤R¥ BQ¤¢ X«)X…€¤ @
.....................................................................................................................................PK t\~ Declaration/Parser.phpnu [ new(location => "file.xml")
or die "cannot read file.xml\n";
while ($reader->read) {
processNode($reader);
}
sub processNode {
my $reader = shift;
printf "%d %d %s %d\n", ($reader->depth,
$reader->nodeType,
$reader->name,
$reader->isEmptyElement);
}
or
my $reader = XML::LibXML::Reader->new(location => "file.xml")
or die "cannot read file.xml\n";
$reader->preservePattern('//table/tr');
$reader->finish;
print $reader->document->toString(1);
=head1 DESCRIPTION
This is a perl interface to libxml2's pull-parser implementation xmlTextReader I<<<<<< http://xmlsoft.org/html/libxml-xmlreader.html >>>>>>. This feature requires at least libxml2-2.6.21. Pull-parsers (such as StAX in
Java, or XmlReader in C#) use an iterator approach to parse XML documents. They
are easier to program than event-based parser (SAX) and much more lightweight
than tree-based parser (DOM), which load the complete tree into memory.
The Reader acts as a cursor going forward on the document stream and stopping
at each node on the way. At every point, the DOM-like methods of the Reader
object allow one to examine the current node (name, namespace, attributes,
etc.)
The user's code keeps control of the progress and simply calls the C<<<<<< read() >>>>>> function repeatedly to progress to the next node in the document order. Other
functions provide means for skipping complete sub-trees, or nodes until a
specific element, etc.
At every time, only a very limited portion of the document is kept in the
memory, which makes the API more memory-efficient than using DOM. However, it
is also possible to mix Reader with DOM. At every point the user may copy the
current node (optionally expanded into a complete sub-tree) from the processed
document to another DOM tree, or to instruct the Reader to collect sub-document
in form of a DOM tree consisting of selected nodes.
Reader API also supports namespaces, xml:base, entity handling, and DTD
validation. Schema and RelaxNG validation support will probably be added in
some later revision of the Perl interface.
The naming of methods compared to libxml2 and C# XmlTextReader has been changed
slightly to match the conventions of XML::LibXML. Some functions have been
changed or added with respect to the C interface.
=head1 CONSTRUCTOR
Depending on the XML source, the Reader object can be created with either of:
my $reader = XML::LibXML::Reader->new( location => "file.xml", ... );
my $reader = XML::LibXML::Reader->new( string => $xml_string, ... );
my $reader = XML::LibXML::Reader->new( IO => $file_handle, ... );
my $reader = XML::LibXML::Reader->new( FD => fileno(STDIN), ... );
my $reader = XML::LibXML::Reader->new( DOM => $dom, ... );
where ... are (optional) reader options described below in L<<<<<< Reader options >>>>>> or various parser options described in L<<<<<< XML::LibXML::Parser >>>>>>. The constructor recognizes the following XML sources:
=head2 Source specification
=over 4
=item location
Read XML from a local file or (non-HTTPS) URL.
=item string
Read XML from a string.
=item IO
Read XML a Perl IO filehandle.
=item FD
Read XML from a file descriptor (bypasses Perl I/O layer, only applicable to
filehandles for regular files or pipes). Possibly faster than IO.
=item DOM
Use reader API to walk through a pre-parsed L<<<<<< XML::LibXML::Document >>>>>>.
=back
=head2 Reader options
=over 4
=item encoding => $encoding
override document encoding.
=item RelaxNG => $rng_schema
can be used to pass either a L<<<<<< XML::LibXML::RelaxNG >>>>>> object or a filename or (non-HTTPS) URL of a RelaxNG schema to the constructor.
The schema is then used to validate the document as it is processed.
=item Schema => $xsd_schema
can be used to pass either a L<<<<<< XML::LibXML::Schema >>>>>> object or a filename or (non-HTTPS) URL of a W3C XSD schema to the constructor.
The schema is then used to validate the document as it is processed.
=item ...
the reader further supports various parser options described in L<<<<<< XML::LibXML::Parser >>>>>> (specifically those labeled by /reader/).
=back
=head1 METHODS CONTROLLING PARSING PROGRESS
=over 4
=item read ()
Moves the position to the next node in the stream, exposing its properties.
Returns 1 if the node was read successfully, 0 if there is no more nodes to
read, or -1 in case of error
=item readAttributeValue ()
Parses an attribute value into one or more Text and EntityReference nodes.
Returns 1 in case of success, 0 if the reader was not positioned on an
attribute node or all the attribute values have been read, or -1 in case of
error.
=item readState ()
Gets the read state of the reader. Returns the state value, or -1 in case of
error. The module exports constants for the Reader states, see STATES below.
=item depth ()
The depth of the node in the tree, starts at 0 for the root node.
=item next ()
Skip to the node following the current one in the document order while avoiding
the sub-tree if any. Returns 1 if the node was read successfully, 0 if there is
no more nodes to read, or -1 in case of error.
=item nextElement (localname?,nsURI?)
Skip nodes following the current one in the document order until a specific
element is reached. The element's name must be equal to a given localname if
defined, and its namespace must equal to a given nsURI if defined. Either of
the arguments can be undefined (or omitted, in case of the latter or both).
Returns 1 if the element was found, 0 if there is no more nodes to read, or -1
in case of error.
=item nextPatternMatch (compiled_pattern)
Skip nodes following the current one in the document order until an element
matching a given compiled pattern is reached. See L<<<<<< XML::LibXML::Pattern >>>>>> for information on compiled patterns. See also the C<<<<<< matchesPattern >>>>>> method.
Returns 1 if the element was found, 0 if there is no more nodes to read, or -1
in case of error.
=item skipSiblings ()
Skip all nodes on the same or lower level until the first node on a higher
level is reached. In particular, if the current node occurs in an element, the
reader stops at the end tag of the parent element, otherwise it stops at a node
immediately following the parent node.
Returns 1 if successful, 0 if end of the document is reached, or -1 in case of
error.
=item nextSibling ()
It skips to the node following the current one in the document order while
avoiding the sub-tree if any.
Returns 1 if the node was read successfully, 0 if there is no more nodes to
read, or -1 in case of error
=item nextSiblingElement (name?,nsURI?)
Like nextElement but only processes sibling elements of the current node
(moving forward using C<<<<<< nextSibling () >>>>>> rather than C<<<<<< read () >>>>>>, internally).
Returns 1 if the element was found, 0 if there is no more sibling nodes, or -1
in case of error.
=item finish ()
Skip all remaining nodes in the document, reaching end of the document.
Returns 1 if successful, 0 in case of error.
=item close ()
This method releases any resources allocated by the current instance and closes
any underlying input. It returns 0 on failure and 1 on success. This method is
automatically called by the destructor when the reader is forgotten, therefore
you do not have to call it directly.
=back
=head1 METHODS EXTRACTING INFORMATION
=over 4
=item name ()
Returns the qualified name of the current node, equal to (Prefix:)LocalName.
=item nodeType ()
Returns the type of the current node. See NODE TYPES below.
=item localName ()
Returns the local name of the node.
=item prefix ()
Returns the prefix of the namespace associated with the node.
=item namespaceURI ()
Returns the URI defining the namespace associated with the node.
=item isEmptyElement ()
Check if the current node is empty, this is a bit bizarre in the sense that
will be considered empty while will not.
=item hasValue ()
Returns true if the node can have a text value.
=item value ()
Provides the text value of the node if present or undef if not available.
=item readInnerXml ()
Reads the contents of the current node, including child nodes and markup.
Returns a string containing the XML of the node's content, or undef if the
current node is neither an element nor attribute, or has no child nodes.
=item readOuterXml ()
Reads the contents of the current node, including child nodes and markup.
Returns a string containing the XML of the node including its content, or undef
if the current node is neither an element nor attribute.
=item nodePath()
Returns a canonical location path to the current element from the root node to
the current node. Namespaced elements are matched by '*', because there is no
way to declare prefixes within XPath patterns. Unlike C<<<<<< XML::LibXML::Node::nodePath() >>>>>>, this function does not provide sibling counts (i.e. instead of e.g. '/a/b[1]'
and '/a/b[2]' you get '/a/b' for both matches).
=item matchesPattern(compiled_pattern)
Returns a true value if the current node matches a compiled pattern. See L<<<<<< XML::LibXML::Pattern >>>>>> for information on compiled patterns. See also the C<<<<<< nextPatternMatch >>>>>> method.
=back
=head1 METHODS EXTRACTING DOM NODES
=over 4
=item document ()
Provides access to the document tree built by the reader. This function can be
used to collect the preserved nodes (see C<<<<<< preserveNode() >>>>>> and preservePattern).
CAUTION: Never use this function to modify the tree unless reading of the whole
document is completed!
=item copyCurrentNode (deep)
This function is similar a DOM function C<<<<<< copyNode() >>>>>>. It returns a copy of the currently processed node as a corresponding DOM
object. Use deep = 1 to obtain the full sub-tree.
=item preserveNode ()
This tells the XML Reader to preserve the current node in the document tree. A
document tree consisting of the preserved nodes and their content can be
obtained using the method C<<<<<< document() >>>>>> once parsing is finished.
Returns the node or NULL in case of error.
=item preservePattern (pattern,\%ns_map)
This tells the XML Reader to preserve all nodes matched by the pattern (which
is a streaming XPath subset). A document tree consisting of the preserved nodes
and their content can be obtained using the method C<<<<<< document() >>>>>> once parsing is finished.
An optional second argument can be used to provide a HASH reference mapping
prefixes used by the XPath to namespace URIs.
The XPath subset available with this function is described at
http://www.w3.org/TR/xmlschema-1/#Selector
and matches the production
Path ::= ('.//')? ( Step '/' )* ( Step | '@' NameTest )
Returns a positive number in case of success and -1 in case of error
=back
=head1 METHODS PROCESSING ATTRIBUTES
=over 4
=item attributeCount ()
Provides the number of attributes of the current node.
=item hasAttributes ()
Whether the node has attributes.
=item getAttribute (name)
Provides the value of the attribute with the specified qualified name.
Returns a string containing the value of the specified attribute, or undef in
case of error.
=item getAttributeNs (localName, namespaceURI)
Provides the value of the specified attribute.
Returns a string containing the value of the specified attribute, or undef in
case of error.
=item getAttributeNo (no)
Provides the value of the attribute with the specified index relative to the
containing element.
Returns a string containing the value of the specified attribute, or undef in
case of error.
=item isDefault ()
Returns true if the current attribute node was generated from the default value
defined in the DTD.
=item moveToAttribute (name)
Moves the position to the attribute with the specified local name and namespace
URI.
Returns 1 in case of success, -1 in case of error, 0 if not found
=item moveToAttributeNo (no)
Moves the position to the attribute with the specified index relative to the
containing element.
Returns 1 in case of success, -1 in case of error, 0 if not found
=item moveToAttributeNs (localName,namespaceURI)
Moves the position to the attribute with the specified local name and namespace
URI.
Returns 1 in case of success, -1 in case of error, 0 if not found
=item moveToFirstAttribute ()
Moves the position to the first attribute associated with the current node.
Returns 1 in case of success, -1 in case of error, 0 if not found
=item moveToNextAttribute ()
Moves the position to the next attribute associated with the current node.
Returns 1 in case of success, -1 in case of error, 0 if not found
=item moveToElement ()
Moves the position to the node that contains the current attribute node.
Returns 1 in case of success, -1 in case of error, 0 if not moved
=item isNamespaceDecl ()
Determine whether the current node is a namespace declaration rather than a
regular attribute.
Returns 1 if the current node is a namespace declaration, 0 if it is a regular
attribute or other type of node, or -1 in case of error.
=back
=head1 OTHER METHODS
=over 4
=item lookupNamespace (prefix)
Resolves a namespace prefix in the scope of the current element.
Returns a string containing the namespace URI to which the prefix maps or undef
in case of error.
=item encoding ()
Returns a string containing the encoding of the document or undef in case of
error.
=item standalone ()
Determine the standalone status of the document being read. Returns 1 if the
document was declared to be standalone, 0 if it was declared to be not
standalone, or -1 if the document did not specify its standalone status or in
case of error.
=item xmlVersion ()
Determine the XML version of the document being read. Returns a string
containing the XML version of the document or undef in case of error.
=item baseURI ()
Returns the base URI of a given node.
=item isValid ()
Retrieve the validity status from the parser.
Returns 1 if valid, 0 if no, and -1 in case of error.
=item xmlLang ()
The xml:lang scope within which the node resides.
=item lineNumber ()
Provide the line number of the current parsing point.
=item columnNumber ()
Provide the column number of the current parsing point.
=item byteConsumed ()
This function provides the current index of the parser relative to the start of
the current entity. This function is computed in bytes from the beginning
starting at zero and finishing at the size in bytes of the file if parsing a
file. The function is of constant cost if the input is UTF-8 but can be costly
if run on non-UTF-8 input.
=item setParserProp (prop => value, ...)
Change the parser processing behaviour by changing some of its internal
properties. The following properties are available with this function:
``load_ext_dtd'', ``complete_attributes'', ``validation'', ``expand_entities''.
Since some of the properties can only be changed before any read has been done,
it is best to set the parsing properties at the constructor.
Returns 0 if the call was successful, or -1 in case of error
=item getParserProp (prop)
Get value of an parser internal property. The following property names can be
used: ``load_ext_dtd'', ``complete_attributes'', ``validation'',
``expand_entities''.
Returns the value, usually 0 or 1, or -1 in case of error.
=back
=head1 DESTRUCTION
XML::LibXML takes care of the reader object destruction when the last reference
to the reader object goes out of scope. The document tree is preserved, though,
if either of $reader->document or $reader->preserveNode was used and references
to the document tree exist.
=head1 NODE TYPES
The reader interface provides the following constants for node types (the
constant symbols are exported by default or if tag C<<<<<< :types >>>>>> is used).
XML_READER_TYPE_NONE => 0
XML_READER_TYPE_ELEMENT => 1
XML_READER_TYPE_ATTRIBUTE => 2
XML_READER_TYPE_TEXT => 3
XML_READER_TYPE_CDATA => 4
XML_READER_TYPE_ENTITY_REFERENCE => 5
XML_READER_TYPE_ENTITY => 6
XML_READER_TYPE_PROCESSING_INSTRUCTION => 7
XML_READER_TYPE_COMMENT => 8
XML_READER_TYPE_DOCUMENT => 9
XML_READER_TYPE_DOCUMENT_TYPE => 10
XML_READER_TYPE_DOCUMENT_FRAGMENT => 11
XML_READER_TYPE_NOTATION => 12
XML_READER_TYPE_WHITESPACE => 13
XML_READER_TYPE_SIGNIFICANT_WHITESPACE => 14
XML_READER_TYPE_END_ELEMENT => 15
XML_READER_TYPE_END_ENTITY => 16
XML_READER_TYPE_XML_DECLARATION => 17
=head1 STATES
The following constants represent the values returned by C<<<<<< readState() >>>>>>. They are exported by default, or if tag C<<<<<< :states >>>>>> is used:
XML_READER_NONE => -1
XML_READER_START => 0
XML_READER_ELEMENT => 1
XML_READER_END => 2
XML_READER_EMPTY => 3
XML_READER_BACKTRACK => 4
XML_READER_DONE => 5
XML_READER_ERROR => 6
=head1 SEE ALSO
L<<<<<< XML::LibXML::Pattern >>>>>> for information about compiled patterns.
http://xmlsoft.org/html/libxml-xmlreader.html
http://dotgnu.org/pnetlib-doc/System/Xml/XmlTextReader.html
=head1 ORIGINAL IMPLEMENTATION
Heiko Klein, and Petr Pajas
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\KS LibXML/SAX/Builder.podnu 6$ =head1 NAME
XML::LibXML::SAX::Builder - Building DOM trees from SAX events.
=head1 SYNOPSIS
use XML::LibXML::SAX::Builder;
my $builder = XML::LibXML::SAX::Builder->new();
my $gen = XML::Generator::DBI->new(Handler => $builder, dbh => $dbh);
$gen->execute("SELECT * FROM Users");
my $doc = $builder->result();
=head1 DESCRIPTION
This is a SAX handler that generates a DOM tree from SAX events. Usage is as
above. Input is accepted from any SAX1 or SAX2 event generator.
Building DOM trees from SAX events is quite easy with
XML::LibXML::SAX::Builder. The class is designed as a SAX2 final handler not as
a filter!
Since SAX is strictly stream oriented, you should not expect anything to return
from a generator. Instead you have to ask the builder instance directly to get
the document built. XML::LibXML::SAX::Builder's result() function holds the
document generated from the last SAX stream.
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\8=4 LibXML/SAX/Builder.pmnu 6$ # $Id$
#
# This is free software, you may use it and distribute it under the same terms as
# Perl itself.
#
# Copyright 2001-2003 AxKit.com Ltd., 2002-2006 Christian Glahn, 2006-2009 Petr Pajas
#
#
package XML::LibXML::SAX::Builder;
use strict;
use warnings;
use XML::LibXML;
use XML::NamespaceSupport;
use vars qw ($VERSION);
sub CLONE_SKIP {
return $XML::LibXML::__threads_shared ? 0 : 1;
}
$VERSION = "2.0210"; # VERSION TEMPLATE: DO NOT CHANGE
sub new {
my $class = shift;
return bless {@_}, $class;
}
sub result { $_[0]->{LAST_DOM}; }
sub done {
my ($self) = @_;
my $dom = $self->{DOM};
$dom = $self->{Parent} unless defined $dom; # this is for parsing document chunks
delete $self->{NamespaceStack};
delete $self->{Parent};
delete $self->{DOM};
$self->{LAST_DOM} = $dom;
return $dom;
}
sub set_document_locator {
}
sub start_dtd {
my ($self, $dtd) = @_;
if (defined $dtd->{Name} and
(defined $dtd->{SystemId} or defined $dtd->{PublicId})) {
$self->{DOM}->createExternalSubset($dtd->{Name},$dtd->{PublicId},$dtd->{SystemId});
}
}
sub end_dtd {
}
sub start_document {
my ($self, $doc) = @_;
$self->{DOM} = XML::LibXML::Document->createDocument();
if ( defined $self->{Encoding} ) {
$self->xml_decl({Version => ($self->{Version} || '1.0') , Encoding => $self->{Encoding}});
}
$self->{NamespaceStack} = XML::NamespaceSupport->new;
$self->{NamespaceStack}->push_context;
$self->{Parent} = undef;
return ();
}
sub xml_decl {
my $self = shift;
my $decl = shift;
if ( defined $decl->{Version} ) {
$self->{DOM}->setVersion( $decl->{Version} );
}
if ( defined $decl->{Encoding} ) {
$self->{DOM}->setEncoding( $decl->{Encoding} );
}
return ();
}
sub end_document {
my ($self, $doc) = @_;
my $d = $self->done();
return $d;
}
sub start_prefix_mapping {
my $self = shift;
my $ns = shift;
unless ( defined $self->{DOM} or defined $self->{Parent} ) {
$self->{Parent} = XML::LibXML::DocumentFragment->new();
$self->{NamespaceStack} = XML::NamespaceSupport->new;
$self->{NamespaceStack}->push_context;
}
$self->{USENAMESPACESTACK} = 1;
$self->{NamespaceStack}->declare_prefix( $ns->{Prefix}, $ns->{NamespaceURI} );
return ();
}
sub end_prefix_mapping {
my $self = shift;
my $ns = shift;
$self->{NamespaceStack}->undeclare_prefix( $ns->{Prefix} );
return ();
}
sub start_element {
my ($self, $el) = @_;
my $node;
unless ( defined $self->{DOM} or defined $self->{Parent} ) {
$self->{Parent} = XML::LibXML::DocumentFragment->new();
$self->{NamespaceStack} = XML::NamespaceSupport->new;
$self->{NamespaceStack}->push_context;
}
if ( defined $self->{Parent} ) {
$el->{NamespaceURI} ||= "";
$node = $self->{Parent}->addNewChild( $el->{NamespaceURI},
$el->{Name} );
}
else {
if ($el->{NamespaceURI}) {
if ( defined $self->{DOM} ) {
$node = $self->{DOM}->createRawElementNS($el->{NamespaceURI},
$el->{Name});
}
else {
$node = XML::LibXML::Element->new( $el->{Name} );
$node->setNamespace( $el->{NamespaceURI},
$el->{Prefix} , 1 );
}
}
else {
if ( defined $self->{DOM} ) {
$node = $self->{DOM}->createRawElement($el->{Name});
}
else {
$node = XML::LibXML::Element->new( $el->{Name} );
}
}
$self->{DOM}->setDocumentElement($node);
}
# build namespaces
my $skip_ns= 0;
foreach my $p ( $self->{NamespaceStack}->get_declared_prefixes() ) {
$skip_ns= 1;
my $uri = $self->{NamespaceStack}->get_uri($p);
my $nodeflag = 0;
if ( defined $uri
and defined $el->{NamespaceURI}
and $uri eq $el->{NamespaceURI} ) {
# $nodeflag = 1;
next;
}
$node->setNamespace($uri, $p, 0 );
}
$self->{Parent} = $node;
$self->{NamespaceStack}->push_context;
# do attributes
foreach my $key (keys %{$el->{Attributes}}) {
my $attr = $el->{Attributes}->{$key};
if (ref($attr)) {
# catch broken name/value pairs
next unless $attr->{Name} ;
next if $self->{USENAMESPACESTACK}
and ( $attr->{Name} eq "xmlns"
or ( defined $attr->{Prefix}
and $attr->{Prefix} eq "xmlns" ) );
if ( defined $attr->{Prefix}
and $attr->{Prefix} eq "xmlns" and $skip_ns == 0 ) {
# ok, the generator does not set namespaces correctly!
my $uri = $attr->{Value};
$node->setNamespace($uri,
$attr->{LocalName},
$uri eq $el->{NamespaceURI} ? 1 : 0 );
}
else {
$node->setAttributeNS($attr->{NamespaceURI} || "",
$attr->{Name}, $attr->{Value});
}
}
else {
$node->setAttribute($key => $attr);
}
}
return ();
}
sub end_element {
my ($self, $el) = @_;
return unless $self->{Parent};
$self->{NamespaceStack}->pop_context;
$self->{Parent} = $self->{Parent}->parentNode();
return ();
}
sub start_cdata {
my $self = shift;
$self->{IN_CDATA} = 1;
return ();
}
sub end_cdata {
my $self = shift;
$self->{IN_CDATA} = 0;
return ();
}
sub characters {
my ($self, $chars) = @_;
if ( not defined $self->{DOM} and not defined $self->{Parent} ) {
$self->{Parent} = XML::LibXML::DocumentFragment->new();
$self->{NamespaceStack} = XML::NamespaceSupport->new;
$self->{NamespaceStack}->push_context;
}
return unless $self->{Parent};
my $node;
unless ( defined $chars and defined $chars->{Data} ) {
return;
}
if ( defined $self->{DOM} ) {
if ( defined $self->{IN_CDATA} and $self->{IN_CDATA} == 1 ) {
$node = $self->{DOM}->createCDATASection($chars->{Data});
}
else {
$node = $self->{Parent}->appendText($chars->{Data});
return;
}
}
elsif ( defined $self->{IN_CDATA} and $self->{IN_CDATA} == 1 ) {
$node = XML::LibXML::CDATASection->new($chars->{Data});
}
else {
$node = XML::LibXML::Text->new($chars->{Data});
}
$self->{Parent}->addChild($node);
return ();
}
sub comment {
my ($self, $chars) = @_;
my $comment;
if ( not defined $self->{DOM} and not defined $self->{Parent} ) {
$self->{Parent} = XML::LibXML::DocumentFragment->new();
$self->{NamespaceStack} = XML::NamespaceSupport->new;
$self->{NamespaceStack}->push_context;
}
unless ( defined $chars and defined $chars->{Data} ) {
return;
}
if ( defined $self->{DOM} ) {
$comment = $self->{DOM}->createComment( $chars->{Data} );
}
else {
$comment = XML::LibXML::Comment->new( $chars->{Data} );
}
if ( defined $self->{Parent} ) {
$self->{Parent}->addChild($comment);
}
else {
$self->{DOM}->addChild($comment);
}
return ();
}
sub processing_instruction {
my ( $self, $pi ) = @_;
my $PI;
return unless defined $self->{DOM};
$PI = $self->{DOM}->createPI( $pi->{Target}, $pi->{Data} );
if ( defined $self->{Parent} ) {
$self->{Parent}->addChild( $PI );
}
else {
$self->{DOM}->addChild( $PI );
}
return ();
}
sub warning {
my $self = shift;
my $error = shift;
# fill $@ but do not die seriously
eval { $error->throw; };
}
sub error {
my $self = shift;
my $error = shift;
delete $self->{NamespaceStack};
delete $self->{Parent};
delete $self->{DOM};
$error->throw;
}
sub fatal_error {
my $self = shift;
my $error = shift;
delete $self->{NamespaceStack};
delete $self->{Parent};
delete $self->{DOM};
$error->throw;
}
1;
__END__
PK N\ׅF LibXML/SAX/Parser.pmnu 6$ # $Id$
#
# This is free software, you may use it and distribute it under the same terms as
# Perl itself.
#
# Copyright 2001-2003 AxKit.com Ltd., 2002-2006 Christian Glahn, 2006-2009 Petr Pajas
#
#
package XML::LibXML::SAX::Parser;
use strict;
use warnings;
use vars qw($VERSION @ISA);
use XML::LibXML;
use XML::LibXML::Common qw(:libxml);
use XML::SAX::Base;
use XML::SAX::DocumentLocator;
$VERSION = "2.0210"; # VERSION TEMPLATE: DO NOT CHANGE
@ISA = ('XML::SAX::Base');
sub CLONE_SKIP {
return $XML::LibXML::__threads_shared ? 0 : 1;
}
sub _parse_characterstream {
my ($self, $fh, $options) = @_;
die "parsing a characterstream is not supported at this time";
}
sub _parse_bytestream {
my ($self, $fh, $options) = @_;
my $parser = XML::LibXML->new();
my $doc = exists($options->{Source}{SystemId}) ? $parser->parse_fh($fh, $options->{Source}{SystemId}) : $parser->parse_fh($fh);
$self->generate($doc);
}
sub _parse_string {
my ($self, $str, $options) = @_;
my $parser = XML::LibXML->new();
my $doc = exists($options->{Source}{SystemId}) ? $parser->parse_string($str, $options->{Source}{SystemId}) : $parser->parse_string($str);
$self->generate($doc);
}
sub _parse_systemid {
my ($self, $sysid, $options) = @_;
my $parser = XML::LibXML->new();
my $doc = $parser->parse_file($sysid);
$self->generate($doc);
}
sub generate {
my $self = shift;
my ($node) = @_;
my $doc = $node->ownerDocument();
{
# precompute some DocumentLocator values
my %locator = (
PublicId => undef,
SystemId => undef,
Encoding => undef,
XMLVersion => undef,
);
my $dtd = defined $doc ? $doc->externalSubset() : undef;
if (defined $dtd) {
$locator{PublicId} = $dtd->publicId();
$locator{SystemId} = $dtd->systemId();
}
if (defined $doc) {
$locator{Encoding} = $doc->encoding();
$locator{XMLVersion} = $doc->version();
}
$self->set_document_locator(
XML::SAX::DocumentLocator->new(
sub { $locator{PublicId} },
sub { $locator{SystemId} },
sub { defined($self->{current_node}) ? $self->{current_node}->line_number() : undef },
sub { 1 },
sub { $locator{Encoding} },
sub { $locator{XMLVersion} },
),
);
}
if ( $node->nodeType() == XML_DOCUMENT_NODE
|| $node->nodeType == XML_HTML_DOCUMENT_NODE ) {
$self->start_document({});
$self->xml_decl({Version => $node->getVersion, Encoding => $node->getEncoding});
$self->process_node($node);
$self->end_document({});
}
}
sub process_node {
my ($self, $node) = @_;
local $self->{current_node} = $node;
my $node_type = $node->nodeType();
if ($node_type == XML_COMMENT_NODE) {
$self->comment( { Data => $node->getData } );
}
elsif ($node_type == XML_TEXT_NODE
|| $node_type == XML_CDATA_SECTION_NODE) {
# warn($node->getData . "\n");
$self->characters( { Data => $node->nodeValue } );
}
elsif ($node_type == XML_ELEMENT_NODE) {
# warn("<" . $node->getName . ">\n");
$self->process_element($node);
# warn("getName . ">\n");
}
elsif ($node_type == XML_ENTITY_REF_NODE) {
foreach my $kid ($node->childNodes) {
# warn("child of entity ref: " . $kid->getType() . " called: " . $kid->getName . "\n");
$self->process_node($kid);
}
}
elsif ($node_type == XML_DOCUMENT_NODE
|| $node_type == XML_HTML_DOCUMENT_NODE
|| $node_type == XML_DOCUMENT_FRAG_NODE) {
# sometimes it is just useful to generate SAX events from
# a document fragment (very good with filters).
foreach my $kid ($node->childNodes) {
$self->process_node($kid);
}
}
elsif ($node_type == XML_PI_NODE) {
$self->processing_instruction( { Target => $node->getName, Data => $node->getData } );
}
elsif ($node_type == XML_COMMENT_NODE) {
$self->comment( { Data => $node->getData } );
}
elsif ( $node_type == XML_XINCLUDE_START
|| $node_type == XML_XINCLUDE_END ) {
# ignore!
# i may want to handle this one day, dunno yet
}
elsif ($node_type == XML_DTD_NODE ) {
# ignore!
# i will support DTDs, but had no time yet.
}
else {
# warn("unsupported node type: $node_type");
}
}
sub process_element {
my ($self, $element) = @_;
my $attribs = {};
my @ns_maps = $element->getNamespaces;
foreach my $ns (@ns_maps) {
$self->start_prefix_mapping(
{
NamespaceURI => $ns->href,
Prefix => ( defined $ns->localname ? $ns->localname : ''),
}
);
}
foreach my $attr ($element->attributes) {
my $key;
# warn("Attr: $attr -> ", $attr->getName, " = ", $attr->getData, "\n");
# this isa dump thing...
if ($attr->isa('XML::LibXML::Namespace')) {
# TODO This needs fixing modulo agreeing on what
# is the right thing to do here.
unless ( defined $attr->name ) {
## It's an atter like "xmlns='foo'"
$attribs->{"{}xmlns"} =
{
Name => "xmlns",
LocalName => "xmlns",
Prefix => "",
Value => $attr->href,
NamespaceURI => "",
};
}
else {
my $prefix = "xmlns";
my $localname = $attr->localname;
my $key = "{http://www.w3.org/2000/xmlns/}";
my $name = "xmlns";
if ( defined $localname ) {
$key .= $localname;
$name.= ":".$localname;
}
$attribs->{$key} =
{
Name => $name,
Value => $attr->href,
NamespaceURI => "http://www.w3.org/2000/xmlns/",
Prefix => $prefix,
LocalName => $localname,
};
}
}
else {
my $ns = $attr->namespaceURI;
$ns = '' unless defined $ns;
$key = "{$ns}".$attr->localname;
## Not sure why, but $attr->name is coming through stripped
## of its prefix, so we need to hand-assemble a real name.
my $name = $attr->name;
$name = "" unless defined $name;
my $prefix = $attr->prefix;
$prefix = "" unless defined $prefix;
$name = "$prefix:$name"
if index( $name, ":" ) < 0 && length $prefix;
$attribs->{$key} =
{
Name => $name,
Value => $attr->value,
NamespaceURI => $ns,
Prefix => $prefix,
LocalName => $attr->localname,
};
}
# use Data::Dumper;
# warn("Attr made: ", Dumper($attribs->{$key}), "\n");
}
my $node = {
Name => $element->nodeName,
Attributes => $attribs,
NamespaceURI => $element->namespaceURI,
Prefix => $element->prefix || "",
LocalName => $element->localname,
};
$self->start_element($node);
foreach my $child ($element->childNodes) {
$self->process_node($child);
}
my $end_node = { %$node };
delete $end_node->{Attributes};
$self->end_element($end_node);
foreach my $ns (@ns_maps) {
$self->end_prefix_mapping(
{
NamespaceURI => $ns->href,
Prefix => ( defined $ns->localname ? $ns->localname : ''),
}
);
}
}
1;
__END__
PK N\e LibXML/SAX/Generator.pmnu 6$ # $Id: Generator.pm 772 2009-01-23 21:42:09Z pajas
#
# This is free software, you may use it and distribute it under the same terms as
# Perl itself.
#
# Copyright 2001-2003 AxKit.com Ltd., 2002-2006 Christian Glahn, 2006-2009 Petr Pajas
#
#
package XML::LibXML::SAX::Generator;
use strict;
use warnings;
use XML::LibXML;
use vars qw ($VERSION);
$VERSION = "2.0210"; # VERSION TEMPLATE: DO NOT CHANGE
sub CLONE_SKIP {
return $XML::LibXML::__threads_shared ? 0 : 1;
}
warn("This class (", __PACKAGE__, ") is deprecated!");
sub new {
my $class = shift;
unshift @_, 'Handler' unless @_ != 1;
my %p = @_;
return bless \%p, $class;
}
sub generate {
my $self = shift;
my ($node) = @_;
my $document = { Parent => undef };
$self->{Handler}->start_document($document);
process_node($self->{Handler}, $node);
$self->{Handler}->end_document($document);
}
sub process_node {
my ($handler, $node) = @_;
my $node_type = $node->getType();
if ($node_type == XML_COMMENT_NODE) {
$handler->comment( { Data => $node->getData } );
}
elsif ($node_type == XML_TEXT_NODE || $node_type == XML_CDATA_SECTION_NODE) {
# warn($node->getData . "\n");
$handler->characters( { Data => $node->getData } );
}
elsif ($node_type == XML_ELEMENT_NODE) {
# warn("<" . $node->getName . ">\n");
process_element($handler, $node);
# warn("getName . ">\n");
}
elsif ($node_type == XML_ENTITY_REF_NODE) {
foreach my $kid ($node->getChildnodes) {
# warn("child of entity ref: " . $kid->getType() . " called: " . $kid->getName . "\n");
process_node($handler, $kid);
}
}
elsif ($node_type == XML_DOCUMENT_NODE) {
# just get root element. Ignore other cruft.
foreach my $kid ($node->getChildnodes) {
if ($kid->getType() == XML_ELEMENT_NODE) {
process_element($handler, $kid);
last;
}
}
}
else {
warn("unknown node type: $node_type");
}
}
sub process_element {
my ($handler, $element) = @_;
my @attr;
foreach my $attr ($element->getAttributes) {
push @attr, XML::LibXML::SAX::AttributeNode->new(
Name => $attr->getName,
Value => $attr->getData,
NamespaceURI => $attr->getNamespaceURI,
Prefix => $attr->getPrefix,
LocalName => $attr->getLocalName,
);
}
my $node = {
Name => $element->getName,
Attributes => { map { $_->{Name} => $_ } @attr },
NamespaceURI => $element->getNamespaceURI,
Prefix => $element->getPrefix,
LocalName => $element->getLocalName,
};
$handler->start_element($node);
foreach my $child ($element->getChildnodes) {
process_node($handler, $child);
}
$handler->end_element($node);
}
package XML::LibXML::SAX::AttributeNode;
use overload '""' => "stringify";
sub new {
my $class = shift;
my %p = @_;
return bless \%p, $class;
}
sub stringify {
my $self = shift;
return $self->{Value};
}
1;
__END__
=head1 NAME
XML::LibXML::SAX::Generator - Generate SAX events from a LibXML tree
=head1 SYNOPSIS
my $handler = MySAXHandler->new();
my $generator = XML::LibXML::SAX::Generator->new(Handler => $handler);
my $dom = XML::LibXML->new->parse_file("foo.xml");
$generator->generate($dom);
=head1 DESCRIPTION
THIS CLASS IS DEPRECATED! Use XML::LibXML::SAX::Parser instead!
This helper class allows you to generate SAX events from any XML::LibXML
node, and all it's sub-nodes. This basically gives you interop from
XML::LibXML to other modules that may implement SAX.
It uses SAX2 style, but should be compatible with anything SAX1, by use
of stringification overloading.
There is nothing to really know about, beyond the synopsis above, and
a general knowledge of how to use SAX, which is beyond the scope here.
=cut
PK N\V
LibXML/PI.podnu 6$ =head1 NAME
XML::LibXML::PI - XML::LibXML Processing Instructions
=head1 SYNOPSIS
use XML::LibXML;
# Only methods specific to Processing Instruction nodes are listed here,
# see the XML::LibXML::Node manpage for other methods
$pinode->setData( $data_string );
$pinode->setData( name=>string_value [...] );
=head1 DESCRIPTION
Processing instructions are implemented with XML::LibXML with read and write
access. The PI data is the PI without the PI target (as specified in XML 1.0
[17]) as a string. This string can be accessed with getData as implemented in L<<<<<< XML::LibXML::Node >>>>>>.
The write access is aware about the fact, that many processing instructions
have attribute like data. Therefore setData() provides besides the DOM spec
conform Interface to pass a set of named parameter. So the code segment
my $pi = $dom->createProcessingInstruction("abc");
$pi->setData(foo=>'bar', foobar=>'foobar');
$dom->appendChild( $pi );
will result the following PI in the DOM:
Which is how it is specified in the DOM specification. This three step
interface creates temporary a node in perl space. This can be avoided while
using the insertProcessingInstruction() method. Instead of the three calls
described above, the call
$dom->insertProcessingInstruction("abc",'foo="bar" foobar="foobar"');
will have the same result as above.
L<<<<<< XML::LibXML::PI >>>>>>'s implementation of setData() documented below differs a bit from the standard
version as available in L<<<<<< XML::LibXML::Node >>>>>>:
=over 4
=item setData
$pinode->setData( $data_string );
$pinode->setData( name=>string_value [...] );
This method allows one to change the content data of a PI. Additionally to the
interface specified for DOM Level2, the method provides a named parameter
interface to set the data. This parameter list is converted into a string
before it is appended to the PI.
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\ LibXML/Attr.podnu 6$ =head1 NAME
XML::LibXML::Attr - XML::LibXML Attribute Class
=head1 SYNOPSIS
use XML::LibXML;
# Only methods specific to Attribute nodes are listed here,
# see the XML::LibXML::Node manpage for other methods
$attr = XML::LibXML::Attr->new($name [,$value]);
$string = $attr->getValue();
$string = $attr->value;
$attr->setValue( $string );
$node = $attr->getOwnerElement();
$attr->setNamespace($nsURI, $prefix);
$bool = $attr->isId;
$string = $attr->serializeContent;
=head1 DESCRIPTION
This is the interface to handle Attributes like ordinary nodes. The naming of
the class relies on the W3C DOM documentation.
=head1 METHODS
The class inherits from L<<<<<< XML::LibXML::Node >>>>>>. The documentation for Inherited methods is not listed here.
Many functions listed here are extensively documented in the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>). Please refer to the specification for extensive documentation.
=over 4
=item new
$attr = XML::LibXML::Attr->new($name [,$value]);
Class constructor. If you need to work with ISO encoded strings, you should I<<<<<< always >>>>>> use the C<<<<<< createAttribute >>>>>> of L<<<<<< XML::LibXML::Document >>>>>>.
=item getValue
$string = $attr->getValue();
Returns the value stored for the attribute. If undef is returned, the attribute
has no value, which is different of being C<<<<<< not specified >>>>>>.
=item value
$string = $attr->value;
Alias for I<<<<<< getValue() >>>>>>
=item setValue
$attr->setValue( $string );
This is needed to set a new attribute value. If ISO encoded strings are passed
as parameter, the node has to be bound to a document, otherwise the encoding
might be done incorrectly.
=item getOwnerElement
$node = $attr->getOwnerElement();
returns the node the attribute belongs to. If the attribute is not bound to a
node, undef will be returned. Overwriting the underlying implementation, the I<<<<<< parentNode >>>>>> function will return undef, instead of the owner element.
=item setNamespace
$attr->setNamespace($nsURI, $prefix);
This function tries to bound the attribute to a given namespace. If C<<<<<< $nsURI >>>>>> is undefined or empty, the function discards any previous association of the
attribute with a namespace. If the namespace was not previously declared in the
context of the attribute, this function will fail. In this case you may wish to
call setNamespace() on the ownerElement. If the namespace URI is non-empty and
declared in the context of the attribute, but only with a different (non-empty)
prefix, then the attribute is still bound to the namespace but gets a different
prefix than C<<<<<< $prefix >>>>>>. The function also fails if the prefix is empty but the namespace URI is not
(because unprefixed attributes should by definition belong to no namespace).
This function returns 1 on success, 0 otherwise.
=item isId
$bool = $attr->isId;
Determine whether an attribute is of type ID. For documents with a DTD, this
information is only available if DTD loading/validation has been requested. For
HTML documents parsed with the HTML parser ID detection is done automatically.
In XML documents, all "xml:id" attributes are considered to be of type ID.
=item serializeContent($docencoding)
$string = $attr->serializeContent;
This function is not part of DOM API. It returns attribute content in the form
in which it serializes into XML, that is with all meta-characters properly
quoted and with raw entity references (except for entities expanded during
parse time). Setting the optional $docencoding flag to 1 enforces document
encoding for the output string (which is then passed to Perl as a byte string).
Otherwise the string is passed to Perl as (UTF-8 encoded) characters.
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\/r5 5 LibXML/Element.podnu 6$ =head1 NAME
XML::LibXML::Element - XML::LibXML Class for Element Nodes
=head1 SYNOPSIS
use XML::LibXML;
# Only methods specific to Element nodes are listed here,
# see the XML::LibXML::Node manpage for other methods
$node = XML::LibXML::Element->new( $name );
$node->setAttribute( $aname, $avalue );
$node->setAttributeNS( $nsURI, $aname, $avalue );
$avalue = $node->getAttribute( $aname );
$avalue = $node->getAttributeNS( $nsURI, $aname );
$attrnode = $node->getAttributeNode( $aname );
$attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
$node->removeAttribute( $aname );
$node->removeAttributeNS( $nsURI, $aname );
$boolean = $node->hasAttribute( $aname );
$boolean = $node->hasAttributeNS( $nsURI, $aname );
@nodes = $node->getChildrenByTagName($tagname);
@nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
@nodes = $node->getChildrenByLocalName($localname);
@nodes = $node->getElementsByTagName($tagname);
@nodes = $node->getElementsByTagNameNS($nsURI,$localname);
@nodes = $node->getElementsByLocalName($localname);
$node->appendWellBalancedChunk( $chunk );
$node->appendText( $PCDATA );
$node->appendTextNode( $PCDATA );
$node->appendTextChild( $childname , $PCDATA );
$node->setNamespace( $nsURI , $nsPrefix, $activate );
$node->setNamespaceDeclURI( $nsPrefix, $newURI );
$node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
=head1 METHODS
The class inherits from L<<<<<< XML::LibXML::Node >>>>>>. The documentation for Inherited methods is not listed here.
Many functions listed here are extensively documented in the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>). Please refer to the specification for extensive documentation.
=over 4
=item new
$node = XML::LibXML::Element->new( $name );
This function creates a new node unbound to any DOM.
=item setAttribute
$node->setAttribute( $aname, $avalue );
This method sets or replaces the node's attribute C<<<<<< $aname >>>>>> to the value C<<<<<< $avalue >>>>>>
=item setAttributeNS
$node->setAttributeNS( $nsURI, $aname, $avalue );
Namespace-aware version of C<<<<<< setAttribute >>>>>>, where C<<<<<< $nsURI >>>>>> is a namespace URI, C<<<<<< $aname >>>>>> is a qualified name, and C<<<<<< $avalue >>>>>> is the value. The namespace URI may be null (empty or undefined) in order to
create an attribute which has no namespace.
The current implementation differs from DOM in the following aspects
If an attribute with the same local name and namespace URI already exists on
the element, but its prefix differs from the prefix of C<<<<<< $aname >>>>>>, then this function is supposed to change the prefix (regardless of namespace
declarations and possible collisions). However, the current implementation does
rather the opposite. If a prefix is declared for the namespace URI in the scope
of the attribute, then the already declared prefix is used, disregarding the
prefix specified in C<<<<<< $aname >>>>>>. If no prefix is declared for the namespace, the function tries to declare the
prefix specified in C<<<<<< $aname >>>>>> and dies if the prefix is already taken by some other namespace.
According to DOM Level 2 specification, this method can also be used to create
or modify special attributes used for declaring XML namespaces (which belong to
the namespace "http://www.w3.org/2000/xmlns/" and have prefix or name "xmlns").
This should work since version 1.61, but again the implementation differs from
DOM specification in the following: if a declaration of the same namespace
prefix already exists on the element, then changing its value via this method
automatically changes the namespace of all elements and attributes in its
scope. This is because in libxml2 the namespace URI of an element is not static
but is computed from a pointer to a namespace declaration attribute.
=item getAttribute
$avalue = $node->getAttribute( $aname );
If C<<<<<< $node >>>>>> has an attribute with the name C<<<<<< $aname >>>>>>, the value of this attribute will get returned.
=item getAttributeNS
$avalue = $node->getAttributeNS( $nsURI, $aname );
Retrieves an attribute value by local name and namespace URI.
=item getAttributeNode
$attrnode = $node->getAttributeNode( $aname );
Retrieve an attribute node by name. If no attribute with a given name exists, C<<<<<< undef >>>>>> is returned.
=item getAttributeNodeNS
$attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
Retrieves an attribute node by local name and namespace URI. If no attribute
with a given localname and namespace exists, C<<<<<< undef >>>>>> is returned.
=item removeAttribute
$node->removeAttribute( $aname );
The method removes the attribute C<<<<<< $aname >>>>>> from the node's attribute list, if the attribute can be found.
=item removeAttributeNS
$node->removeAttributeNS( $nsURI, $aname );
Namespace version of C<<<<<< removeAttribute >>>>>>
=item hasAttribute
$boolean = $node->hasAttribute( $aname );
This function tests if the named attribute is set for the node. If the
attribute is specified, TRUE (1) will be returned, otherwise the return value
is FALSE (0).
=item hasAttributeNS
$boolean = $node->hasAttributeNS( $nsURI, $aname );
namespace version of C<<<<<< hasAttribute >>>>>>
=item getChildrenByTagName
@nodes = $node->getChildrenByTagName($tagname);
The function gives direct access to all child elements of the current node with
a given tagname, where tagname is a qualified name, that is, in case of
namespace usage it may consist of a prefix and local name. This function makes
things a lot easier if one needs to handle big data sets. A special tagname '*'
can be used to match any name.
If this function is called in SCALAR context, it returns the number of elements
found.
=item getChildrenByTagNameNS
@nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
Namespace version of C<<<<<< getChildrenByTagName >>>>>>. A special nsURI '*' matches any namespace URI, in which case the function
behaves just like C<<<<<< getChildrenByLocalName >>>>>>.
If this function is called in SCALAR context, it returns the number of elements
found.
=item getChildrenByLocalName
@nodes = $node->getChildrenByLocalName($localname);
The function gives direct access to all child elements of the current node with
a given local name. It makes things a lot easier if one needs to handle big
data sets. A special C<<<<<< localname >>>>>> '*' can be used to match any local name.
If this function is called in SCALAR context, it returns the number of elements
found.
=item getElementsByTagName
@nodes = $node->getElementsByTagName($tagname);
This function is part of the spec. It fetches all descendants of a node with a
given tagname, where C<<<<<< tagname >>>>>> is a qualified name, that is, in case of namespace usage it may consist of a
prefix and local name. A special C<<<<<< tagname >>>>>> '*' can be used to match any tag name.
In SCALAR context this function returns an L<<<<<< XML::LibXML::NodeList >>>>>> object.
=item getElementsByTagNameNS
@nodes = $node->getElementsByTagNameNS($nsURI,$localname);
Namespace version of C<<<<<< getElementsByTagName >>>>>> as found in the DOM spec. A special C<<<<<< localname >>>>>> '*' can be used to match any local name and C<<<<<< nsURI >>>>>> '*' can be used to match any namespace URI.
In SCALAR context this function returns an L<<<<<< XML::LibXML::NodeList >>>>>> object.
=item getElementsByLocalName
@nodes = $node->getElementsByLocalName($localname);
This function is not found in the DOM specification. It is a mix of
getElementsByTagName and getElementsByTagNameNS. It will fetch all tags
matching the given local-name. This allows one to select tags with the same
local name across namespace borders.
In SCALAR context this function returns an L<<<<<< XML::LibXML::NodeList >>>>>> object.
=item appendWellBalancedChunk
$node->appendWellBalancedChunk( $chunk );
Sometimes it is necessary to append a string coded XML Tree to a node. I<<<<<< appendWellBalancedChunk >>>>>> will do the trick for you. But this is only done if the String is C<<<<<< well-balanced >>>>>>.
I<<<<<< Note that appendWellBalancedChunk() is only left for compatibility reasons >>>>>>. Implicitly it uses
my $fragment = $parser->parse_balanced_chunk( $chunk );
$node->appendChild( $fragment );
This form is more explicit and makes it easier to control the flow of a script.
=item appendText
$node->appendText( $PCDATA );
alias for appendTextNode().
=item appendTextNode
$node->appendTextNode( $PCDATA );
This wrapper function lets you add a string directly to an element node.
=item appendTextChild
$node->appendTextChild( $childname , $PCDATA );
Somewhat similar with C<<<<<< appendTextNode >>>>>>: It lets you set an Element, that contains only a C<<<<<< text node >>>>>> directly by specifying the name and the text content.
=item setNamespace
$node->setNamespace( $nsURI , $nsPrefix, $activate );
setNamespace() allows one to apply a namespace to an element. The function
takes three parameters: 1. the namespace URI, which is required and the two
optional values prefix, which is the namespace prefix, as it should be used in
child elements or attributes as well as the additional activate parameter. If
prefix is not given, undefined or empty, this function tries to create a
declaration of the default namespace.
The activate parameter is most useful: If this parameter is set to FALSE (0), a
new namespace declaration is simply added to the element while the element's
namespace itself is not altered. Nevertheless, activate is set to TRUE (1) on
default. In this case the namespace is used as the node's effective namespace.
This means the namespace prefix is added to the node name and if there was a
namespace already active for the node, it will be replaced (but its declaration
is not removed from the document). A new namespace declaration is only created
if necessary (that is, if the element is already in the scope of a namespace
declaration associating the prefix with the namespace URI, then this
declaration is reused).
The following example may clarify this:
my $e1 = $doc->createElement("bar");
$e1->setNamespace("http://foobar.org", "foo")
results
while
my $e2 = $doc->createElement("bar");
$e2->setNamespace("http://foobar.org", "foo",0)
results only
By using $activate == 0 it is possible to create multiple namespace
declarations on a single element.
The function fails if it is required to create a declaration associating the
prefix with the namespace URI but the element already carries a declaration
with the same prefix but different namespace URI.
=item setNamespaceDeclURI
$node->setNamespaceDeclURI( $nsPrefix, $newURI );
EXPERIMENTAL IN 1.61 !
This function manipulates directly with an existing namespace declaration on an
element. It takes two parameters: the prefix by which it looks up the namespace
declaration and a new namespace URI which replaces its previous value.
It returns 1 if the namespace declaration was found and changed, 0 otherwise.
All elements and attributes (even those previously unbound from the document)
for which the namespace declaration determines their namespace belong to the
new namespace after the change.
If the new URI is undef or empty, the nodes have no namespace and no prefix
after the change. Namespace declarations once nulled in this way do not further
appear in the serialized output (but do remain in the document for internal
integrity of libxml2 data structures).
This function is NOT part of any DOM API.
=item setNamespaceDeclPrefix
$node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );
EXPERIMENTAL IN 1.61 !
This function manipulates directly with an existing namespace declaration on an
element. It takes two parameters: the old prefix by which it looks up the
namespace declaration and a new prefix which is to replace the old one.
The function dies with an error if the element is in the scope of another
declaration whose prefix equals to the new prefix, or if the change should
result in a declaration with a non-empty prefix but empty namespace URI.
Otherwise, it returns 1 if the namespace declaration was found and changed and
0 if not found.
All elements and attributes (even those previously unbound from the document)
for which the namespace declaration determines their namespace change their
prefix to the new value.
If the new prefix is undef or empty, the namespace declaration becomes a
declaration of a default namespace. The corresponding nodes drop their
namespace prefix (but remain in the, now default, namespace). In this case the
function fails, if the containing element is in the scope of another default
namespace declaration.
This function is NOT part of any DOM API.
=back
=head1 OVERLOADING
XML::LibXML::Element overloads hash dereferencing to provide access to the
element's attributes. For non-namespaced attributes, the attribute name is the
hash key, and the attribute value is the hash value. For namespaced attributes,
the hash key is qualified with the namespace URI, using Clark notation.
Perl's "tied hash" feature is used, which means that the hash gives you
read-write access to the element's attributes. For more information, see L<<<<<< XML::LibXML::AttributeHash >>>>>>
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\8B LibXML/Schema.podnu 6$ =head1 NAME
XML::LibXML::Schema - XML Schema Validation
=head1 SYNOPSIS
use XML::LibXML;
$doc = XML::LibXML->new->parse_file($url);
$xmlschema = XML::LibXML::Schema->new( location => $filename_or_url, no_network => 1 );
$xmlschema = XML::LibXML::Schema->new( string => $xmlschemastring, no_network => 1 );
eval { $xmlschema->validate( $doc ); };
=head1 DESCRIPTION
The XML::LibXML::Schema class is a tiny frontend to libxml2's XML Schema
implementation. Currently it supports only schema parsing and document
validation. As of 2.6.32, libxml2 only supports decimal types up to 24 digits
(the standard requires at least 18).
=head1 METHODS
=over 4
=item new
$xmlschema = XML::LibXML::Schema->new( location => $filename_or_url, no_network => 1 );
$xmlschema = XML::LibXML::Schema->new( string => $xmlschemastring, no_network => 1 );
The constructor of XML::LibXML::Schema needs to be called with list of
parameters. At least location or string parameter is required to specify source
of schema. Optional parameter no_network set to 1 cause that parser would not
access network and optional parameter recover set 1 cause that parser would not
call die() on errors.
It is important, that each schema only have a single source.
The location parameter allows one to parse a schema from the filesystem or a
(non-HTTPS) URL.
The string parameter will parse the schema from the given XML string.
Note that the constructor will die() if the schema does not meed the
constraints of the XML Schema specification.
=item validate
eval { $xmlschema->validate( $doc ); };
This function allows one to validate a (parsed) document against the given XML
Schema. The argument of this function should be a L<<<<<< XML::LibXML::Document >>>>>> object. If this function succeeds, it will return 0, otherwise it will die()
and report the errors found. Because of this validate() should be always
evaluated.
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\No&^& ^& LibXML/InputCallback.podnu 6$ =head1 NAME
XML::LibXML::InputCallback - XML::LibXML Class for Input Callbacks
=head1 SYNOPSIS
use XML::LibXML;
=head1 DESCRIPTION
You may get unexpected results if you are trying to load external documents
during libxml2 parsing if the location of the resource is not a HTTP, FTP or
relative location but a absolute path for example. To get around this
limitation, you may add your own input handler to open, read and close
particular types of locations or URI classes. Using this input callback
handlers, you can handle your own custom URI schemes for example.
The input callbacks are used whenever XML::LibXML has to get something other
than externally parsed entities from somewhere. They are implemented using a
callback stack on the Perl layer in analogy to libxml2's native callback stack.
The XML::LibXML::InputCallback class transparently registers the input
callbacks for the libxml2's parser processes.
=head2 How does XML::LibXML::InputCallback work?
The libxml2 library offers a callback implementation as global functions only.
To work-around the troubles resulting in having only global callbacks - for
example, if the same global callback stack is manipulated by different
applications running together in a single Apache Web-server environment -,
XML::LibXML::InputCallback comes with a object-oriented and a function-oriented
part.
Using the function-oriented part the global callback stack of libxml2 can be
manipulated. Those functions can be used as interface to the callbacks on the
C- and XS Layer. At the object-oriented part, operations for working with the
"pseudo-localized" callback stack are implemented. Currently, you can register
and de-register callbacks on the Perl layer and initialize them on a per parser
basis.
=head3 Callback Groups
The libxml2 input callbacks come in groups. One group contains a URI matcher (I<<<<<< match >>>>>>), a data stream constructor (I<<<<<< open >>>>>>), a data stream reader (I<<<<<< read >>>>>>), and a data stream destructor (I<<<<<< close >>>>>>). The callbacks can be manipulated on a per group basis only.
=head3 The Parser Process
The parser process works on an XML data stream, along which, links to other
resources can be embedded. This can be links to external DTDs or XIncludes for
example. Those resources are identified by URIs. The callback implementation of
libxml2 assumes that one callback group can handle a certain amount of URIs and
a certain URI scheme. Per default, callback handlers for I<<<<<< file://* >>>>>>, I<<<<<< file:://*.gz >>>>>>, I<<<<<< http://* >>>>>> and I<<<<<< ftp://* >>>>>> are registered.
Callback groups in the callback stack are processed from top to bottom, meaning
that callback groups registered later will be processed before the earlier
registered ones.
While parsing the data stream, the libxml2 parser checks if a registered
callback group will handle a URI - if they will not, the URI will be
interpreted as I<<<<<< file://URI >>>>>>. To handle a URI, the I<<<<<< match >>>>>> callback will have to return '1'. If that happens, the handling of the URI will
be passed to that callback group. Next, the URI will be passed to the I<<<<<< open >>>>>> callback, which should return a I<<<<<< reference >>>>>> to the data stream if it successfully opened the file, '0' otherwise. If
opening the stream was successful, the I<<<<<< read >>>>>> callback will be called repeatedly until it returns an empty string. After the
read callback, the I<<<<<< close >>>>>> callback will be called to close the stream.
=head3 Organisation of callback groups in XML::LibXML::InputCallback
Callback groups are implemented as a stack (Array), each entry holds a
reference to an array of the callbacks. For the libxml2 library, the
XML::LibXML::InputCallback callback implementation appears as one single
callback group. The Perl implementation however allows one to manage different
callback stacks on a per libxml2-parser basis.
=head2 Using XML::LibXML::InputCallback
After object instantiation using the parameter-less constructor, you can
register callback groups.
my $input_callbacks = XML::LibXML::InputCallback->new();
$input_callbacks->register_callbacks([ $match_cb1, $open_cb1,
$read_cb1, $close_cb1 ] );
$input_callbacks->register_callbacks([ $match_cb2, $open_cb2,
$read_cb2, $close_cb2 ] );
$input_callbacks->register_callbacks( [ $match_cb3, $open_cb3,
$read_cb3, $close_cb3 ] );
$parser->input_callbacks( $input_callbacks );
$parser->parse_file( $some_xml_file );
=head2 What about the old callback system prior to XML::LibXML::InputCallback?
In XML::LibXML versions prior to 1.59 - i.e. without the
XML::LibXML::InputCallback module - you could define your callbacks either
using globally or locally. You still can do that using
XML::LibXML::InputCallback, and in addition to that you can define the
callbacks on a per parser basis!
If you use the old callback interface through global callbacks,
XML::LibXML::InputCallback will treat them with a lower priority as the ones
registered using the new interface. The global callbacks will not override the
callback groups registered using the new interface. Local callbacks are
attached to a specific parser instance, therefore they are treated with highest
priority. If the I<<<<<< match >>>>>> callback of the callback group registered as local variable is identical to one
of the callback groups registered using the new interface, that callback group
will be replaced.
Users of the old callback implementation whose I<<<<<< open >>>>>> callback returned a plain string, will have to adapt their code to return a
reference to that string after upgrading to version >= 1.59. The new callback
system can only deal with the I<<<<<< open >>>>>> callback returning a reference!
=head1 INTERFACE DESCRIPTION
=head2 Global Variables
=over 4
=item $_CUR_CB
Stores the current callback and can be used as shortcut to access the callback
stack.
=item @_GLOBAL_CALLBACKS
Stores all callback groups for the current parser process.
=item @_CB_STACK
Stores the currently used callback group. Used to prevent parser errors when
dealing with nested XML data.
=back
=head2 Global Callbacks
=over 4
=item _callback_match
Implements the interface for the I<<<<<< match >>>>>> callback at C-level and for the selection of the callback group from the
callbacks defined at the Perl-level.
=item _callback_open
Forwards the I<<<<<< open >>>>>> callback from libxml2 to the corresponding callback function at the Perl-level.
=item _callback_read
Forwards the read request to the corresponding callback function at the
Perl-level and returns the result to libxml2.
=item _callback_close
Forwards the I<<<<<< close >>>>>> callback from libxml2 to the corresponding callback function at the
Perl-level..
=back
=head2 Class methods
=over 4
=item new()
A simple constructor.
=item register_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])
The four callbacks I<<<<<< have >>>>>> to be given as array reference in the above order I<<<<<< match >>>>>>, I<<<<<< open >>>>>>, I<<<<<< read >>>>>>, I<<<<<< close >>>>>>!
=item unregister_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])
With no arguments given, C<<<<<< unregister_callbacks() >>>>>> will delete the last registered callback group from the stack. If four
callbacks are passed as array reference, the callback group to unregister will
be identified by the I<<<<<< match >>>>>> callback and deleted from the callback stack. Note that if several identical I<<<<<< match >>>>>> callbacks are defined in different callback groups, ALL of them will be deleted
from the stack.
=item init_callbacks( $parser )
Initializes the callback system for the provided parser before starting a
parsing process.
=item cleanup_callbacks()
Resets global variables and the libxml2 callback stack.
=item lib_init_callbacks()
Used internally for callback registration at C-level.
=item lib_cleanup_callbacks()
Used internally for callback resetting at the C-level.
=back
=head1 EXAMPLE CALLBACKS
The following example is a purely fictitious example that uses a
MyScheme::Handler object that responds to methods similar to an IO::Handle.
# Define the four callback functions
sub match_uri {
my $uri = shift;
return $uri =~ /^myscheme:/; # trigger our callback group at a 'myscheme' URIs
}
sub open_uri {
my $uri = shift;
my $handler = MyScheme::Handler->new($uri);
return $handler;
}
# The returned $buffer will be parsed by the libxml2 parser
sub read_uri {
my $handler = shift;
my $length = shift;
my $buffer;
read($handler, $buffer, $length);
return $buffer; # $buffer will be an empty string '' if read() is done
}
# Close the handle associated with the resource.
sub close_uri {
my $handler = shift;
close($handler);
}
# Register them with a instance of XML::LibXML::InputCallback
my $input_callbacks = XML::LibXML::InputCallback->new();
$input_callbacks->register_callbacks([ \&match_uri, \&open_uri,
\&read_uri, \&close_uri ] );
# Register the callback group at a parser instance
$parser->input_callbacks( $input_callbacks );
# $some_xml_file will be parsed using our callbacks
$parser->parse_file( $some_xml_file );
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\YT YT LibXML/Document.podnu 6$ =head1 NAME
XML::LibXML::Document - XML::LibXML DOM Document Class
=head1 SYNOPSIS
use XML::LibXML;
# Only methods specific to Document nodes are listed here,
# see the XML::LibXML::Node manpage for other methods
$dom = XML::LibXML::Document->new( $version, $encoding );
$dom = XML::LibXML::Document->createDocument( $version, $encoding );
$strURI = $doc->URI();
$doc->setURI($strURI);
$strEncoding = $doc->encoding();
$strEncoding = $doc->actualEncoding();
$doc->setEncoding($new_encoding);
$strVersion = $doc->version();
$doc->standalone
$doc->setStandalone($numvalue);
my $compression = $doc->compression;
$doc->setCompression($ziplevel);
$docstring = $dom->toString($format);
$c14nstr = $doc->toStringC14N($comment_flag, $xpath [, $xpath_context ]);
$ec14nstr = $doc->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
$str = $doc->serialize($format);
$state = $doc->toFile($filename, $format);
$state = $doc->toFH($fh, $format);
$str = $document->toStringHTML();
$str = $document->serialize_html();
$bool = $dom->is_valid();
$dom->validate();
$root = $dom->documentElement();
$dom->setDocumentElement( $root );
$element = $dom->createElement( $nodename );
$element = $dom->createElementNS( $namespaceURI, $nodename );
$text = $dom->createTextNode( $content_text );
$comment = $dom->createComment( $comment_text );
$attrnode = $doc->createAttribute($name [,$value]);
$attrnode = $doc->createAttributeNS( namespaceURI, $name [,$value] );
$fragment = $doc->createDocumentFragment();
$cdata = $dom->createCDATASection( $cdata_content );
my $pi = $doc->createProcessingInstruction( $target, $data );
my $entref = $doc->createEntityReference($refname);
$dtd = $document->createInternalSubset( $rootnode, $public, $system);
$dtd = $document->createExternalSubset( $rootnode_name, $publicId, $systemId);
$document->importNode( $node );
$document->adoptNode( $node );
my $dtd = $doc->externalSubset;
my $dtd = $doc->internalSubset;
$doc->setExternalSubset($dtd);
$doc->setInternalSubset($dtd);
my $dtd = $doc->removeExternalSubset();
my $dtd = $doc->removeInternalSubset();
my @nodelist = $doc->getElementsByTagName($tagname);
my @nodelist = $doc->getElementsByTagNameNS($nsURI,$tagname);
my @nodelist = $doc->getElementsByLocalName($localname);
my $node = $doc->getElementById($id);
$dom->indexElements();
=head1 DESCRIPTION
The Document Class is in most cases the result of a parsing process. But
sometimes it is necessary to create a Document from scratch. The DOM Document
Class provides functions that conform to the DOM Core naming style.
It inherits all functions from L<<<<<< XML::LibXML::Node >>>>>> as specified in the DOM specification. This enables access to the nodes besides
the root element on document level - a C<<<<<< DTD >>>>>> for example. The support for these nodes is limited at the moment.
While generally nodes are bound to a document in the DOM concept it is
suggested that one should always create a node not bound to any document. There
is no need of really including the node to the document, but once the node is
bound to a document, it is quite safe that all strings have the correct
encoding. If an unbound text node with an ISO encoded string is created (e.g.
with $CLASS->new()), the C<<<<<< toString >>>>>> function may not return the expected result.
To prevent such problems, it is recommended to pass all data to XML::LibXML
methods as character strings (i.e. UTF-8 encoded, with the UTF8 flag on).
=head1 METHODS
Many functions listed here are extensively documented in the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>). Please refer to the specification for extensive documentation.
=over 4
=item new
$dom = XML::LibXML::Document->new( $version, $encoding );
alias for createDocument()
=item createDocument
$dom = XML::LibXML::Document->createDocument( $version, $encoding );
The constructor for the document class. As Parameter it takes the version
string and (optionally) the encoding string. Simply calling I<<<<<< createDocument >>>>>>() will create the document:
Both parameter are optional. The default value for I<<<<<< $version >>>>>> is C<<<<<< 1.0 >>>>>>, of course. If the I<<<<<< $encoding >>>>>> parameter is not set, the encoding will be left unset, which means UTF-8 is
implied.
The call of I<<<<<< createDocument >>>>>>() without any parameter will result the following code:
Alternatively one can call this constructor directly from the XML::LibXML class
level, to avoid some typing. This will not have any effect on the class
instance, which is always XML::LibXML::Document.
my $document = XML::LibXML->createDocument( "1.0", "UTF-8" );
is therefore a shortcut for
my $document = XML::LibXML::Document->createDocument( "1.0", "UTF-8" );
=item URI
$strURI = $doc->URI();
Returns the URI (or filename) of the original document. For documents obtained
by parsing a string of a FH without using the URI parsing argument of the
corresponding C<<<<<< parse_* >>>>>> function, the result is a generated string unknown-XYZ where XYZ is some
number; for documents created with the constructor C<<<<<< new >>>>>>, the URI is undefined.
The value can be modified by calling C<<<<<< setURI >>>>>> method on the document node.
=item setURI
$doc->setURI($strURI);
Sets the URI of the document reported by the method URI (see also the URI
argument to the various C<<<<<< parse_* >>>>>> functions).
=item encoding
$strEncoding = $doc->encoding();
returns the encoding string of the document.
my $doc = XML::LibXML->createDocument( "1.0", "ISO-8859-15" );
print $doc->encoding; # prints ISO-8859-15
=item actualEncoding
$strEncoding = $doc->actualEncoding();
returns the encoding in which the XML will be returned by $doc->toString().
This is usually the original encoding of the document as declared in the XML
declaration and returned by $doc->encoding. If the original encoding is not
known (e.g. if created in memory or parsed from a XML without a declared
encoding), 'UTF-8' is returned.
my $doc = XML::LibXML->createDocument( "1.0", "ISO-8859-15" );
print $doc->encoding; # prints ISO-8859-15
=item setEncoding
$doc->setEncoding($new_encoding);
This method allows one to change the declaration of encoding in the XML
declaration of the document. The value also affects the encoding in which the
document is serialized to XML by $doc->toString(). Use setEncoding() to remove
the encoding declaration.
=item version
$strVersion = $doc->version();
returns the version string of the document
I<<<<<< getVersion() >>>>>> is an alternative form of this function.
=item standalone
$doc->standalone
This function returns the Numerical value of a documents XML declarations
standalone attribute. It returns I<<<<<< 1 >>>>>> if standalone="yes" was found, I<<<<<< 0 >>>>>> if standalone="no" was found and I<<<<<< -1 >>>>>> if standalone was not specified (default on creation).
=item setStandalone
$doc->setStandalone($numvalue);
Through this method it is possible to alter the value of a documents standalone
attribute. Set it to I<<<<<< 1 >>>>>> to set standalone="yes", to I<<<<<< 0 >>>>>> to set standalone="no" or set it to I<<<<<< -1 >>>>>> to remove the standalone attribute from the XML declaration.
=item compression
my $compression = $doc->compression;
libxml2 allows reading of documents directly from gzipped files. In this case
the compression variable is set to the compression level of that file (0-8). If
XML::LibXML parsed a different source or the file wasn't compressed, the
returned value will be I<<<<<< -1 >>>>>>.
=item setCompression
$doc->setCompression($ziplevel);
If one intends to write the document directly to a file, it is possible to set
the compression level for a given document. This level can be in the range from
0 to 8. If XML::LibXML should not try to compress use I<<<<<< -1 >>>>>> (default).
Note that this feature will I<<<<<< only >>>>>> work if libxml2 is compiled with zlib support and toFile() is used for output.
=item toString
$docstring = $dom->toString($format);
I<<<<<< toString >>>>>> is a DOM serializing function, so the DOM Tree is serialized into an XML
string, ready for output.
IMPORTANT: unlike toString for other nodes, on document nodes this function
returns the XML as a byte string in the original encoding of the document (see
the actualEncoding() method)! This means you can simply do:
open my $out_fh, '>', $file;
print {$out_fh} $doc->toString;
regardless of the actual encoding of the document. See the section on encodings
in L<<<<<< XML::LibXML >>>>>> for more details.
The optional I<<<<<< $format >>>>>> parameter sets the indenting of the output. This parameter is expected to be an C<<<<<< integer >>>>>> value, that specifies that indentation should be used. The format parameter can
have three different values if it is used:
If $format is 0, than the document is dumped as it was originally parsed
If $format is 1, libxml2 will add ignorable white spaces, so the nodes content
is easier to read. Existing text nodes will not be altered
If $format is 2 (or higher), libxml2 will act as $format == 1 but it add a
leading and a trailing line break to each text node.
libxml2 uses a hard-coded indentation of 2 space characters per indentation
level. This value can not be altered on run-time.
=item toStringC14N
$c14nstr = $doc->toStringC14N($comment_flag, $xpath [, $xpath_context ]);
See the documentation in L<<<<<< XML::LibXML::Node >>>>>>.
=item toStringEC14N
$ec14nstr = $doc->toStringEC14N($comment_flag, $xpath [, $xpath_context ], $inclusive_prefix_list);
See the documentation in L<<<<<< XML::LibXML::Node >>>>>>.
=item serialize
$str = $doc->serialize($format);
An alias for toString(). This function was name added to be more consistent
with libxml2.
=item serialize_c14n
An alias for toStringC14N().
=item serialize_exc_c14n
An alias for toStringEC14N().
=item toFile
$state = $doc->toFile($filename, $format);
This function is similar to toString(), but it writes the document directly
into a filesystem. This function is very useful, if one needs to store large
documents.
The format parameter has the same behaviour as in toString().
=item toFH
$state = $doc->toFH($fh, $format);
This function is similar to toString(), but it writes the document directly to
a filehandle or a stream. A byte stream in the document encoding is passed to
the file handle. Do NOT apply any C<<<<<< :encoding(...) >>>>>> or C<<<<<< :utf8 >>>>>> PerlIO layer to the filehandle! See the section on encodings in L<<<<<< XML::LibXML >>>>>> for more details.
The format parameter has the same behaviour as in toString().
=item toStringHTML
$str = $document->toStringHTML();
I<<<<<< toStringHTML >>>>>> serialize the tree to a byte string in the document encoding as HTML. With this
method indenting is automatic and managed by libxml2 internally. Note the
string must contain (rather than the newer ), else all
non-ASCII will become entities.
=item serialize_html
$str = $document->serialize_html();
An alias for toStringHTML().
=item is_valid
$bool = $dom->is_valid();
Returns either TRUE or FALSE depending on whether the DOM Tree is a valid
Document or not.
You may also pass in a L<<<<<< XML::LibXML::Dtd >>>>>> object, to validate against an external DTD:
if (!$dom->is_valid($dtd)) {
warn("document is not valid!");
}
=item validate
$dom->validate();
This is an exception throwing equivalent of is_valid. If the document is not
valid it will throw an exception containing the error. This allows you much
better error reporting than simply is_valid or not.
Again, you may pass in a DTD object
=item documentElement
$root = $dom->documentElement();
Returns the root element of the Document. A document can have just one root
element to contain the documents data.
Optionally one can use I<<<<<< getDocumentElement >>>>>>.
=item setDocumentElement
$dom->setDocumentElement( $root );
This function enables you to set the root element for a document. The function
supports the import of a node from a different document tree, but does not
support a document fragment as $root.
=item createElement
$element = $dom->createElement( $nodename );
This function creates a new Element Node bound to the DOM with the name C<<<<<< $nodename >>>>>>.
=item createElementNS
$element = $dom->createElementNS( $namespaceURI, $nodename );
This function creates a new Element Node bound to the DOM with the name C<<<<<< $nodename >>>>>> and placed in the given namespace.
=item createTextNode
$text = $dom->createTextNode( $content_text );
As an equivalent of I<<<<<< createElement >>>>>>, but it creates a I<<<<<< Text Node >>>>>> bound to the DOM.
=item createComment
$comment = $dom->createComment( $comment_text );
As an equivalent of I<<<<<< createElement >>>>>>, but it creates a I<<<<<< Comment Node >>>>>> bound to the DOM.
=item createAttribute
$attrnode = $doc->createAttribute($name [,$value]);
Creates a new Attribute node.
=item createAttributeNS
$attrnode = $doc->createAttributeNS( namespaceURI, $name [,$value] );
Creates an Attribute bound to a namespace.
=item createDocumentFragment
$fragment = $doc->createDocumentFragment();
This function creates a DocumentFragment.
=item createCDATASection
$cdata = $dom->createCDATASection( $cdata_content );
Similar to createTextNode and createComment, this function creates a
CDataSection bound to the current DOM.
=item createProcessingInstruction
my $pi = $doc->createProcessingInstruction( $target, $data );
create a processing instruction node.
Since this method is quite long one may use its short form I<<<<<< createPI() >>>>>>.
=item createEntityReference
my $entref = $doc->createEntityReference($refname);
If a document has a DTD specified, one can create entity references by using
this function. If one wants to add a entity reference to the document, this
reference has to be created by this function.
An entity reference is unique to a document and cannot be passed to other
documents as other nodes can be passed.
I<<<<<< NOTE: >>>>>> A text content containing something that looks like an entity reference, will
not be expanded to a real entity reference unless it is a predefined entity
my $string = "&foo;";
$some_element->appendText( $string );
print $some_element->textContent; # prints "&foo;"
=item createInternalSubset
$dtd = $document->createInternalSubset( $rootnode, $public, $system);
This function creates and adds an internal subset to the given document.
Because the function automatically adds the DTD to the document there is no
need to add the created node explicitly to the document.
my $document = XML::LibXML::Document->new();
my $dtd = $document->createInternalSubset( "foo", undef, "foo.dtd" );
will result in the following XML document:
By setting the public parameter it is possible to set PUBLIC DTDs to a given
document. So
my $document = XML::LibXML::Document->new();
my $dtd = $document->createInternalSubset( "foo", "-//FOO//DTD FOO 0.1//EN", undef );
will cause the following declaration to be created on the document:
=item createExternalSubset
$dtd = $document->createExternalSubset( $rootnode_name, $publicId, $systemId);
This function is similar to C<<<<<< createInternalSubset() >>>>>> but this DTD is considered to be external and is therefore not added to the
document itself. Nevertheless it can be used for validation purposes.
=item importNode
$document->importNode( $node );
If a node is not part of a document, it can be imported to another document. As
specified in DOM Level 2 Specification the Node will not be altered or removed
from its original document (C<<<<<< $node-EcloneNode(1) >>>>>> will get called implicitly).
I<<<<<< NOTE: >>>>>> Don't try to use importNode() to import sub-trees that contain an entity
reference - even if the entity reference is the root node of the sub-tree. This
will cause serious problems to your program. This is a limitation of libxml2
and not of XML::LibXML itself.
=item adoptNode
$document->adoptNode( $node );
If a node is not part of a document, it can be imported to another document. As
specified in DOM Level 3 Specification the Node will not be altered but it will
removed from its original document.
After a document adopted a node, the node, its attributes and all its
descendants belong to the new document. Because the node does not belong to the
old document, it will be unlinked from its old location first.
I<<<<<< NOTE: >>>>>> Don't try to adoptNode() to import sub-trees that contain entity references -
even if the entity reference is the root node of the sub-tree. This will cause
serious problems to your program. This is a limitation of libxml2 and not of
XML::LibXML itself.
=item externalSubset
my $dtd = $doc->externalSubset;
If a document has an external subset defined it will be returned by this
function.
I<<<<<< NOTE >>>>>> Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in
XML::LibXML is still limited. In particular one may not want use common node
function on doctype declaration nodes!
=item internalSubset
my $dtd = $doc->internalSubset;
If a document has an internal subset defined it will be returned by this
function.
I<<<<<< NOTE >>>>>> Dtd nodes are no ordinary nodes in libxml2. The support for these nodes in
XML::LibXML is still limited. In particular one may not want use common node
function on doctype declaration nodes!
=item setExternalSubset
$doc->setExternalSubset($dtd);
I<<<<<< EXPERIMENTAL! >>>>>>
This method sets a DTD node as an external subset of the given document.
=item setInternalSubset
$doc->setInternalSubset($dtd);
I<<<<<< EXPERIMENTAL! >>>>>>
This method sets a DTD node as an internal subset of the given document.
=item removeExternalSubset
my $dtd = $doc->removeExternalSubset();
I<<<<<< EXPERIMENTAL! >>>>>>
If a document has an external subset defined it can be removed from the
document by using this function. The removed dtd node will be returned.
=item removeInternalSubset
my $dtd = $doc->removeInternalSubset();
I<<<<<< EXPERIMENTAL! >>>>>>
If a document has an internal subset defined it can be removed from the
document by using this function. The removed dtd node will be returned.
=item getElementsByTagName
my @nodelist = $doc->getElementsByTagName($tagname);
Implements the DOM Level 2 function
In SCALAR context this function returns an L<<<<<< XML::LibXML::NodeList >>>>>> object.
=item getElementsByTagNameNS
my @nodelist = $doc->getElementsByTagNameNS($nsURI,$tagname);
Implements the DOM Level 2 function
In SCALAR context this function returns an L<<<<<< XML::LibXML::NodeList >>>>>> object.
=item getElementsByLocalName
my @nodelist = $doc->getElementsByLocalName($localname);
This allows the fetching of all nodes from a given document with the given
Localname.
In SCALAR context this function returns an L<<<<<< XML::LibXML::NodeList >>>>>> object.
=item getElementById
my $node = $doc->getElementById($id);
Returns the element that has an ID attribute with the given value. If no such
element exists, this returns undef.
Note: the ID of an element may change while manipulating the document. For
documents with a DTD, the information about ID attributes is only available if
DTD loading/validation has been requested. For HTML documents parsed with the
HTML parser ID detection is done automatically. In XML documents, all "xml:id"
attributes are considered to be of type ID. You can test ID-ness of an
attribute node with $attr->isId().
In versions 1.59 and earlier this method was called getElementsById() (plural)
by mistake. Starting from 1.60 this name is maintained as an alias only for
backward compatibility.
=item indexElements
$dom->indexElements();
This function causes libxml2 to stamp all elements in a document with their
document position index which considerably speeds up XPath queries for large
documents. It should only be used with static documents that won't be further
changed by any DOM methods, because once a document is indexed, XPath will
always prefer the index to other methods of determining the document order of
nodes. XPath could therefore return improperly ordered node-lists when applied
on a document that has been changed after being indexed. It is of course
possible to use this method to re-index a modified document before using it
with XPath again. This function is not a part of the DOM specification.
This function returns number of elements indexed, -1 if error occurred, or -2
if this feature is not available in the running libxml2.
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\p[ LibXML/Dtd.podnu 6$ =head1 NAME
XML::LibXML::Dtd - XML::LibXML DTD Handling
=head1 SYNOPSIS
use XML::LibXML;
$dtd = XML::LibXML::Dtd->new($public_id, $system_id);
$dtd = XML::LibXML::Dtd->parse_string($dtd_str);
$publicId = $dtd->getName();
$publicId = $dtd->publicId();
$systemId = $dtd->systemId();
=head1 DESCRIPTION
This class holds a DTD. You may parse a DTD from either a string, or from an
external SYSTEM identifier.
No support is available as yet for parsing from a filehandle.
XML::LibXML::Dtd is a sub-class of L<<<<<< XML::LibXML::Node >>>>>>, so all the methods available to nodes (particularly toString()) are available
to Dtd objects.
=head1 METHODS
=over 4
=item new
$dtd = XML::LibXML::Dtd->new($public_id, $system_id);
Parse a DTD from the system identifier, and return a DTD object that you can
pass to $doc->is_valid() or $doc->validate().
my $dtd = XML::LibXML::Dtd->new(
"SOME // Public / ID / 1.0",
"test.dtd"
);
my $doc = XML::LibXML->new->parse_file("test.xml");
$doc->validate($dtd);
=item parse_string
$dtd = XML::LibXML::Dtd->parse_string($dtd_str);
The same as new() above, except you can parse a DTD from a string. Note that
parsing from string may fail if the DTD contains external parametric-entity
references with relative URLs.
=item getName
$publicId = $dtd->getName();
Returns the name of DTD; i.e., the name immediately following the DOCTYPE
keyword.
=item publicId
$publicId = $dtd->publicId();
Returns the public identifier of the external subset.
=item systemId
$systemId = $dtd->systemId();
Returns the system identifier of the external subset.
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\iw LibXML/Reader.pmnu 6$ # $Id: Reader.pm,v 1.1.2.1 2004/04/20 20:09:48 pajas Exp $
#
# This is free software, you may use it and distribute it under the same terms as
# Perl itself.
#
# Copyright 2001-2003 AxKit.com Ltd., 2002-2006 Christian Glahn, 2006-2009 Petr Pajas
#
#
package XML::LibXML::Reader;
use XML::LibXML;
use Carp;
use strict;
use warnings;
use vars qw ($VERSION);
$VERSION = "2.0210"; # VERSION TEMPLATE: DO NOT CHANGE
use 5.008_000;
BEGIN {
UNIVERSAL::can('XML::LibXML::Reader','_newForFile') or
croak("Cannot use XML::LibXML::Reader module - ".
"your libxml2 is compiled without reader support!");
}
use base qw(Exporter);
use constant {
XML_READER_TYPE_NONE => 0,
XML_READER_TYPE_ELEMENT => 1,
XML_READER_TYPE_ATTRIBUTE => 2,
XML_READER_TYPE_TEXT => 3,
XML_READER_TYPE_CDATA => 4,
XML_READER_TYPE_ENTITY_REFERENCE => 5,
XML_READER_TYPE_ENTITY => 6,
XML_READER_TYPE_PROCESSING_INSTRUCTION => 7,
XML_READER_TYPE_COMMENT => 8,
XML_READER_TYPE_DOCUMENT => 9,
XML_READER_TYPE_DOCUMENT_TYPE => 10,
XML_READER_TYPE_DOCUMENT_FRAGMENT => 11,
XML_READER_TYPE_NOTATION => 12,
XML_READER_TYPE_WHITESPACE => 13,
XML_READER_TYPE_SIGNIFICANT_WHITESPACE => 14,
XML_READER_TYPE_END_ELEMENT => 15,
XML_READER_TYPE_END_ENTITY => 16,
XML_READER_TYPE_XML_DECLARATION => 17,
XML_READER_NONE => -1,
XML_READER_START => 0,
XML_READER_ELEMENT => 1,
XML_READER_END => 2,
XML_READER_EMPTY => 3,
XML_READER_BACKTRACK => 4,
XML_READER_DONE => 5,
XML_READER_ERROR => 6
};
use vars qw( @EXPORT @EXPORT_OK %EXPORT_TAGS );
sub CLONE_SKIP { 1 }
BEGIN {
%EXPORT_TAGS = (
types =>
[qw(
XML_READER_TYPE_NONE
XML_READER_TYPE_ELEMENT
XML_READER_TYPE_ATTRIBUTE
XML_READER_TYPE_TEXT
XML_READER_TYPE_CDATA
XML_READER_TYPE_ENTITY_REFERENCE
XML_READER_TYPE_ENTITY
XML_READER_TYPE_PROCESSING_INSTRUCTION
XML_READER_TYPE_COMMENT
XML_READER_TYPE_DOCUMENT
XML_READER_TYPE_DOCUMENT_TYPE
XML_READER_TYPE_DOCUMENT_FRAGMENT
XML_READER_TYPE_NOTATION
XML_READER_TYPE_WHITESPACE
XML_READER_TYPE_SIGNIFICANT_WHITESPACE
XML_READER_TYPE_END_ELEMENT
XML_READER_TYPE_END_ENTITY
XML_READER_TYPE_XML_DECLARATION
)],
states =>
[qw(
XML_READER_NONE
XML_READER_START
XML_READER_ELEMENT
XML_READER_END
XML_READER_EMPTY
XML_READER_BACKTRACK
XML_READER_DONE
XML_READER_ERROR
)]
);
@EXPORT = (@{$EXPORT_TAGS{types}},@{$EXPORT_TAGS{states}});
@EXPORT_OK = @EXPORT;
$EXPORT_TAGS{all}=\@EXPORT_OK;
}
our %_preserve_flag;
{
my %props = (
load_ext_dtd => 1, # load the external subset
complete_attributes => 2, # default DTD attributes
validation => 3, # validate with the DTD
expand_entities => 4, # substitute entities
);
sub getParserProp {
my ($self, $name) = @_;
my $prop = $props{$name};
return undef unless defined $prop;
return $self->_getParserProp($prop);
}
sub setParserProp {
my $self = shift;
my %args = map { ref($_) eq 'HASH' ? (%$_) : $_ } @_;
my ($key, $value);
while (($key,$value) = each %args) {
my $prop = $props{ $key };
$self->_setParserProp($prop,$value);
}
return;
}
my (%string_pool,%rng_pool,%xsd_pool); # used to preserve data passed to the reader
sub new {
my ($class) = shift;
my %args = map { ref($_) eq 'HASH' ? (%$_) : $_ } @_;
my $encoding = $args{encoding};
my $URI = $args{URI};
$URI="$URI" if defined $URI; # stringify in case it is an URI object
my $options = XML::LibXML->_parser_options(\%args);
my $self = undef;
if ( defined $args{location} ) {
$self = $class->_newForFile( $args{location}, $encoding, $options );
}
elsif ( defined $args{string} ) {
$self = $class->_newForString( $args{string}, $URI, $encoding, $options );
if (defined($self)) {
$string_pool{$self} = \$args{string};
}
}
elsif ( defined $args{IO} ) {
$self = $class->_newForIO( $args{IO}, $URI, $encoding, $options );
}
elsif ( defined $args{DOM} ) {
croak("DOM must be a XML::LibXML::Document node")
unless UNIVERSAL::isa($args{DOM}, 'XML::LibXML::Document');
$self = $class->_newForDOM( $args{DOM} );
}
elsif ( defined $args{FD} ) {
my $fd = fileno($args{FD});
$self = $class->_newForFd( $fd, $URI, $encoding, $options );
}
else {
croak("XML::LibXML::Reader->new: specify location, string, IO, DOM, or FD");
}
if ($args{RelaxNG}) {
if (ref($args{RelaxNG})) {
$rng_pool{$self} = \$args{RelaxNG};
$self->_setRelaxNG($args{RelaxNG});
} else {
$self->_setRelaxNGFile($args{RelaxNG});
}
}
if ($args{Schema}) {
if (ref($args{Schema})) {
$xsd_pool{$self} = \$args{Schema};
$self->_setXSD($args{Schema});
} else {
$self->_setXSDFile($args{Schema});
}
}
return $self;
}
sub DESTROY {
my $self = shift;
delete $string_pool{$self};
delete $rng_pool{$self};
delete $xsd_pool{$self};
$self->_DESTROY;
}
}
sub close {
my ($reader) = @_;
# _close return -1 on failure, 0 on success
# perl close returns 0 on failure, 1 on success
return $reader->_close == 0 ? 1 : 0;
}
sub preservePattern {
my $reader=shift;
my ($pattern,$ns_map)=@_;
if (ref($ns_map) eq 'HASH') {
# translate prefix=>URL hash to a (URL,prefix) list
$reader->_preservePattern($pattern,[reverse %$ns_map]);
} else {
$reader->_preservePattern(@_);
}
}
sub nodePath {
my $reader=shift;
my $path = $reader->_nodePath;
$path=~s/\[\d+\]//g; # make /foo[1]/bar[1] just /foo/bar, since
# sibling count in the buffered fragment is
# basically random and generally misleading
return $path;
}
1;
__END__
PK N\W . . LibXML/Literal.pmnu 6$ # $Id$
#
# This is free software, you may use it and distribute it under the same terms as
# Perl itself.
#
# Copyright 2001-2003 AxKit.com Ltd., 2002-2006 Christian Glahn, 2006-2009 Petr Pajas
#
#
package XML::LibXML::Literal;
use XML::LibXML::Boolean;
use XML::LibXML::Number;
use strict;
use warnings;
use vars qw ($VERSION);
$VERSION = "2.0210"; # VERSION TEMPLATE: DO NOT CHANGE
use overload
'""' => \&value,
'cmp' => \&cmp;
sub new {
my $class = shift;
my ($string) = @_;
# $string =~ s/"/"/g;
# $string =~ s/'/'/g;
bless \$string, $class;
}
sub as_string {
my $self = shift;
my $string = $$self;
$string =~ s/'/'/g;
return "'$string'";
}
sub as_xml {
my $self = shift;
my $string = $$self;
return "$string\n";
}
sub value {
my $self = shift;
$$self;
}
sub cmp {
my $self = shift;
my ($cmp, $swap) = @_;
if ($swap) {
return $cmp cmp $$self;
}
return $$self cmp $cmp;
}
sub evaluate {
my $self = shift;
$self;
}
sub to_boolean {
my $self = shift;
return (length($$self) > 0) ? XML::LibXML::Boolean->True : XML::LibXML::Boolean->False;
}
sub to_number { return XML::LibXML::Number->new($_[0]->value); }
sub to_literal { return $_[0]; }
sub string_value { return $_[0]->value; }
1;
__END__
=head1 NAME
XML::LibXML::Literal - Simple string values.
=head1 DESCRIPTION
In XPath terms a Literal is what we know as a string.
=head1 API
=head2 new($string)
Create a new Literal object with the value in $string. Note that " and
' will be converted to " and ' respectively. That is not part of the XPath
specification, but I consider it useful. Note though that you have to go
to extraordinary lengths in an XML template file (be it XSLT or whatever) to
make use of this:
Which produces a Literal of:
I'm feeling "sad"
=head2 value()
Also overloaded as stringification, simply returns the literal string value.
=head2 cmp($literal)
Returns the equivalent of perl's cmp operator against the given $literal.
=cut
PK N\0 O O LibXML/ErrNo.podnu 6$ =head1 NAME
XML::LibXML::ErrNo - Structured Errors
=head1 DESCRIPTION
This module is based on xmlerror.h libxml2 C header file. It defines symbolic
constants for all libxml2 error codes. Currently libxml2 uses over 480
different error codes. See also XML::LibXML::Error.
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\"O[y# # LibXML/CDATASection.podnu 6$ =head1 NAME
XML::LibXML::CDATASection - XML::LibXML Class for CDATA Sections
=head1 SYNOPSIS
use XML::LibXML;
# Only methods specific to CDATA nodes are listed here,
# see the XML::LibXML::Node manpage for other methods
$node = XML::LibXML::CDATASection->new( $content );
=head1 DESCRIPTION
This class provides all functions of L<<<<<< XML::LibXML::Text >>>>>>, but for CDATA nodes.
=head1 METHODS
The class inherits from L<<<<<< XML::LibXML::Node >>>>>>. The documentation for Inherited methods is not listed here.
Many functions listed here are extensively documented in the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>). Please refer to the specification for extensive documentation.
=over 4
=item new
$node = XML::LibXML::CDATASection->new( $content );
The constructor is the only provided function for this package. It is required,
because I<<<<<< libxml2 >>>>>> treats the different text node types slightly differently.
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\>w LibXML/XPathExpression.podnu 6$ =head1 NAME
XML::LibXML::XPathExpression - XML::LibXML::XPathExpression - interface to libxml2 pre-compiled XPath expressions
=head1 SYNOPSIS
use XML::LibXML;
my $compiled_xpath = XML::LibXML::XPathExpression->new('//foo[@bar="baz"][position()<4]');
# interface from XML::LibXML::Node
my $result = $node->find($compiled_xpath);
my @nodes = $node->findnodes($compiled_xpath);
my $value = $node->findvalue($compiled_xpath);
# interface from XML::LibXML::XPathContext
my $result = $xpc->find($compiled_xpath,$node);
my @nodes = $xpc->findnodes($compiled_xpath,$node);
my $value = $xpc->findvalue($compiled_xpath,$node);
$compiled = XML::LibXML::XPathExpression->new( xpath_string );
=head1 DESCRIPTION
This is a perl interface to libxml2's pre-compiled XPath expressions.
Pre-compiling an XPath expression can give in some performance benefit if the
same XPath query is evaluated many times. C<<<<<< XML::LibXML::XPathExpression >>>>>> objects can be passed to all C<<<<<< find... >>>>>> functions C<<<<<< XML::LibXML >>>>>> that expect an XPath expression.
=over 4
=item new()
$compiled = XML::LibXML::XPathExpression->new( xpath_string );
The constructor takes an XPath 1.0 expression as a string and returns an object
representing the pre-compiled expressions (the actual data structure is
internal to libxml2).
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\jTvA A LibXML/Boolean.pmnu 6$ # $Id$
#
#
# This is free software, you may use it and distribute it under the same terms as
# Perl itself.
#
# Copyright 2001-2003 AxKit.com Ltd., 2002-2006 Christian Glahn, 2006-2009 Petr Pajas
#
#
package XML::LibXML::Boolean;
use XML::LibXML::Number;
use XML::LibXML::Literal;
use strict;
use warnings;
use vars qw ($VERSION);
$VERSION = "2.0210"; # VERSION TEMPLATE: DO NOT CHANGE
use overload
'""' => \&value,
'<=>' => \&cmp;
sub new {
my $class = shift;
my ($param) = @_;
my $val = $param ? 1 : 0;
bless \$val, $class;
}
sub True {
my $class = shift;
my $val = 1;
bless \$val, $class;
}
sub False {
my $class = shift;
my $val = 0;
bless \$val, $class;
}
sub value {
my $self = shift;
$$self;
}
sub cmp {
my $self = shift;
my ($other, $swap) = @_;
if ($swap) {
return $other <=> $$self;
}
return $$self <=> $other;
}
sub to_number { XML::LibXML::Number->new($_[0]->value); }
sub to_boolean { $_[0]; }
sub to_literal { XML::LibXML::Literal->new($_[0]->value ? "true" : "false"); }
sub string_value { return $_[0]->to_literal->value; }
1;
__END__
=head1 NAME
XML::LibXML::Boolean - Boolean true/false values
=head1 DESCRIPTION
XML::LibXML::Boolean objects implement simple boolean true/false objects.
=head1 API
=head2 XML::LibXML::Boolean->True
Creates a new Boolean object with a true value.
=head2 XML::LibXML::Boolean->False
Creates a new Boolean object with a false value.
=head2 value()
Returns true or false.
=head2 to_literal()
Returns the string "true" or "false".
=cut
PK N\;! ! LibXML/Error.pmnu 6$ # $Id: Error.pm,v 1.1.2.1 2004/04/20 20:09:48 pajas Exp $
#
# This is free software, you may use it and distribute it under the same terms as
# Perl itself.
#
# Copyright 2001-2003 AxKit.com Ltd., 2002-2006 Christian Glahn, 2006-2009 Petr Pajas
#
#
package XML::LibXML::Error;
use strict;
use warnings;
# To avoid a "Deep recursion on subroutine as_string" warning
no warnings 'recursion';
use Encode ();
use vars qw(@error_domains $VERSION $WARNINGS);
use overload
'""' => \&as_string,
'eq' => sub {
("$_[0]" eq "$_[1]")
},
'cmp' => sub {
("$_[0]" cmp "$_[1]")
},
fallback => 1;
$WARNINGS = 0; # 0: suppress, 1: report via warn, 2: report via die
$VERSION = "2.0210"; # VERSION TEMPLATE: DO NOT CHANGE
use constant XML_ERR_NONE => 0;
use constant XML_ERR_WARNING => 1; # A simple warning
use constant XML_ERR_ERROR => 2; # A recoverable error
use constant XML_ERR_FATAL => 3; # A fatal error
use constant XML_ERR_FROM_NONE => 0;
use constant XML_ERR_FROM_PARSER => 1; # The XML parser
use constant XML_ERR_FROM_TREE => 2; # The tree module
use constant XML_ERR_FROM_NAMESPACE => 3; # The XML Namespace module
use constant XML_ERR_FROM_DTD => 4; # The XML DTD validation
use constant XML_ERR_FROM_HTML => 5; # The HTML parser
use constant XML_ERR_FROM_MEMORY => 6; # The memory allocator
use constant XML_ERR_FROM_OUTPUT => 7; # The serialization code
use constant XML_ERR_FROM_IO => 8; # The Input/Output stack
use constant XML_ERR_FROM_FTP => 9; # The FTP module
use constant XML_ERR_FROM_HTTP => 10; # The FTP module
use constant XML_ERR_FROM_XINCLUDE => 11; # The XInclude processing
use constant XML_ERR_FROM_XPATH => 12; # The XPath module
use constant XML_ERR_FROM_XPOINTER => 13; # The XPointer module
use constant XML_ERR_FROM_REGEXP => 14; # The regular expressions module
use constant XML_ERR_FROM_DATATYPE => 15; # The W3C XML Schemas Datatype module
use constant XML_ERR_FROM_SCHEMASP => 16; # The W3C XML Schemas parser module
use constant XML_ERR_FROM_SCHEMASV => 17; # The W3C XML Schemas validation module
use constant XML_ERR_FROM_RELAXNGP => 18; # The Relax-NG parser module
use constant XML_ERR_FROM_RELAXNGV => 19; # The Relax-NG validator module
use constant XML_ERR_FROM_CATALOG => 20; # The Catalog module
use constant XML_ERR_FROM_C14N => 21; # The Canonicalization module
use constant XML_ERR_FROM_XSLT => 22; # The XSLT engine from libxslt
use constant XML_ERR_FROM_VALID => 23; # The DTD validation module with valid context
use constant XML_ERR_FROM_CHECK => 24; # The error-checking module
use constant XML_ERR_FROM_WRITER => 25; # The xmlwriter module
use constant XML_ERR_FROM_MODULE => 26; # The dynamically-loaded module module
use constant XML_ERR_FROM_I18N => 27; # The module handling character conversion
use constant XML_ERR_FROM_SCHEMATRONV=> 28; # The Schematron validator module
@error_domains = ("", "parser", "tree", "namespace", "validity",
"HTML parser", "memory", "output", "I/O", "ftp",
"http", "XInclude", "XPath", "xpointer", "regexp",
"Schemas datatype", "Schemas parser", "Schemas validity",
"Relax-NG parser", "Relax-NG validity",
"Catalog", "C14N", "XSLT", "validity", "error-checking",
"xmlwriter", "dynamic loading", "i18n",
"Schematron validity");
my $MAX_ERROR_PREV_DEPTH = 100;
for my $field (qw) {
my $method = sub { $_[0]{$field} };
no strict 'refs';
*$field = $method;
}
{
sub new {
my ($class,$xE) = @_;
my $terr;
if (ref($xE)) {
my ($context,$column) = $xE->context_and_column();
$terr =bless {
domain => $xE->domain(),
level => $xE->level(),
code => $xE->code(),
message => $xE->message(),
file => $xE->file(),
line => $xE->line(),
str1 => $xE->str1(),
str2 => $xE->str2(),
str3 => $xE->str3(),
num1 => $xE->num1(),
num2 => $xE->num2(),
__prev_depth => 0,
(defined($context) ?
(
context => $context,
column => $column,
) : ()),
}, $class;
} else {
# !!!! problem : got a flat error
# warn("PROBLEM: GOT A FLAT ERROR $xE\n");
$terr =bless {
domain => 0,
level => 2,
code => -1,
message => $xE,
file => undef,
line => undef,
str1 => undef,
str2 => undef,
str3 => undef,
num1 => undef,
num2 => undef,
__prev_depth => 0,
}, $class;
}
return $terr;
}
sub _callback_error {
#print "CALLBACK\n";
my ($xE,$prev) = @_;
my $terr;
$terr=XML::LibXML::Error->new($xE);
if ($terr->{level} == XML_ERR_WARNING and $WARNINGS!=2) {
warn $terr if $WARNINGS;
return $prev;
}
#unless ( defined $terr->{file} and length $terr->{file} ) {
# this would make it easier to recognize parsed strings
# but it breaks old implementations
# [CG] $terr->{file} = 'string()';
#}
#warn "Saving the error ",$terr->dump;
if (ref($prev))
{
if ($prev->__prev_depth() >= $MAX_ERROR_PREV_DEPTH)
{
return $prev;
}
$terr->{_prev} = $prev;
$terr->{__prev_depth} = $prev->__prev_depth() + 1;
}
else
{
$terr->{_prev} = defined($prev) && length($prev) ? XML::LibXML::Error->new($prev) : undef;
}
return $terr;
}
sub _instant_error_callback {
my $xE = shift;
my $terr= XML::LibXML::Error->new($xE);
print "Reporting an instanteous error ",$terr->dump;
die $terr;
}
sub _report_warning {
my ($saved_error) = @_;
#print "CALLBACK WARN\n";
if ( defined $saved_error ) {
#print "reporting a warning ",$saved_error->dump;
warn $saved_error;
}
}
sub _report_error {
my ($saved_error) = @_;
#print "CALLBACK ERROR: $saved_error\n";
if ( defined $saved_error ) {
die $saved_error;
}
}
}
# backward compatibility
sub int1 { $_[0]->num1 }
sub int2 { $_[0]->num2 }
sub domain {
my ($self)=@_;
return undef unless ref($self);
my $domain = $self->{domain};
# Newer versions of libxml2 might yield errors in domains that aren't
# listed above. Invent something reasonable in that case.
return $domain < @error_domains ? $error_domains[$domain] : "domain_$domain";
}
sub as_string {
my ($self)=@_;
my $msg = "";
my $level;
if (defined($self->{_prev})) {
$msg = $self->{_prev}->as_string;
}
if ($self->{level} == XML_ERR_NONE) {
$level = "";
} elsif ($self->{level} == XML_ERR_WARNING) {
$level = "warning";
} elsif ($self->{level} == XML_ERR_ERROR ||
$self->{level} == XML_ERR_FATAL) {
$level = "error";
}
my $where="";
if (defined($self->{file})) {
$where="$self->{file}:$self->{line}";
} elsif (($self->{domain} == XML_ERR_FROM_PARSER)
and
$self->{line}) {
$where="Entity: line $self->{line}";
}
if ($self->{nodename}) {
$where.=": element ".$self->{nodename};
}
$msg.=$where.": " if $where ne "";
$msg.=$self->domain." ".$level." :";
my $str=$self->{message}||"";
chomp($str);
$msg.=" ".$str."\n";
if (($self->{domain} == XML_ERR_FROM_XPATH) and
defined($self->{str1})) {
$msg.=$self->{str1}."\n";
$msg.=(" " x $self->{num1})."^\n";
} elsif (defined $self->{context}) {
# If the error relates to character-encoding problems in the context,
# then doing textual operations on it will spew warnings that
# XML::LibXML can do nothing to fix. So just disable all such
# warnings. This has the pleasing benefit of making the test suite
# run warning-free.
no warnings 'utf8';
my $context = Encode::encode('UTF-8', $self->{context});
$msg.=$context."\n";
$context = substr($context,0,$self->{column});
$context=~s/[^\t]/ /g;
$msg.=$context."^\n";
}
return $msg;
}
sub dump {
my ($self)=@_;
require Data::Dumper;
return Data::Dumper->new([$self],['error'])->Dump;
}
1;
PK N\b/Xf f LibXML/Node.podnu 6$ =head1 NAME
XML::LibXML::Node - Abstract Base Class of XML::LibXML Nodes
=head1 SYNOPSIS
use XML::LibXML;
$name = $node->nodeName;
$node->setNodeName( $newName );
$bool = $node->isSameNode( $other_node );
$bool = $node->isEqual( $other_node );
$num = $node->unique_key;
$content = $node->nodeValue;
$content = $node->textContent;
$type = $node->nodeType;
$node->unbindNode();
$childnode = $node->removeChild( $childnode );
$oldnode = $node->replaceChild( $newNode, $oldNode );
$node->replaceNode($newNode);
$childnode = $node->appendChild( $childnode );
$childnode = $node->addChild( $childnode );
$node = $parent->addNewChild( $nsURI, $name );
$node->addSibling($newNode);
$newnode =$node->cloneNode( $deep );
$parentnode = $node->parentNode;
$nextnode = $node->nextSibling();
$nextnode = $node->nextNonBlankSibling();
$prevnode = $node->previousSibling();
$prevnode = $node->previousNonBlankSibling();
$boolean = $node->hasChildNodes();
$childnode = $node->firstChild;
$childnode = $node->lastChild;
$documentnode = $node->ownerDocument;
$node = $node->getOwner;
$node->setOwnerDocument( $doc );
$node->insertBefore( $newNode, $refNode );
$node->insertAfter( $newNode, $refNode );
@nodes = $node->findnodes( $xpath_expression );
$result = $node->find( $xpath );
print $node->findvalue( $xpath );
$bool = $node->exists( $xpath_expression );
@childnodes = $node->childNodes();
@childnodes = $node->nonBlankChildNodes();
$xmlstring = $node->toString($format,$docencoding);
$c14nstring = $node->toStringC14N();
$c14nstring = $node->toStringC14N($with_comments, $xpath_expression , $xpath_context);
$c14nstring = $node->toStringC14N_v1_1();
$c14nstring = $node->toStringC14N_v1_1($with_comments, $xpath_expression , $xpath_context);
$ec14nstring = $node->toStringEC14N();
$ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
$ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
$str = $doc->serialize($format);
$localname = $node->localname;
$nameprefix = $node->prefix;
$uri = $node->namespaceURI();
$boolean = $node->hasAttributes();
@attributelist = $node->attributes();
$URI = $node->lookupNamespaceURI( $prefix );
$prefix = $node->lookupNamespacePrefix( $URI );
$node->normalize;
@nslist = $node->getNamespaces;
$node->removeChildNodes();
$strURI = $node->baseURI();
$node->setBaseURI($strURI);
$node->nodePath();
$lineno = $node->line_number();
=head1 DESCRIPTION
XML::LibXML::Node defines functions that are common to all Node Types. An
XML::LibXML::Node should never be created standalone, but as an instance of a
high level class such as XML::LibXML::Element or XML::LibXML::Text. The class
itself should provide only common functionality. In XML::LibXML each node is
part either of a document or a document-fragment. Because of this there is no
node without a parent. This may causes confusion with "unbound" nodes.
=head1 METHODS
Many functions listed here are extensively documented in the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>). Please refer to the specification for extensive documentation.
=over 4
=item nodeName
$name = $node->nodeName;
Returns the node's name. This function is aware of namespaces and returns the
full name of the current node (C<<<<<< prefix:localname >>>>>>).
Since 1.62 this function also returns the correct DOM names for node types with
constant names, namely: #text, #cdata-section, #comment, #document,
#document-fragment.
=item setNodeName
$node->setNodeName( $newName );
In very limited situations, it is useful to change a nodes name. In the DOM
specification this should throw an error. This Function is aware of namespaces.
=item isSameNode
$bool = $node->isSameNode( $other_node );
returns TRUE (1) if the given nodes refer to the same node structure, otherwise
FALSE (0) is returned.
=item isEqual
$bool = $node->isEqual( $other_node );
deprecated version of isSameNode().
I<<<<<< NOTE >>>>>> isEqual will change behaviour to follow the DOM specification
=item unique_key
$num = $node->unique_key;
This function is not specified for any DOM level. It returns a key guaranteed
to be unique for this node, and to always be the same value for this node. In
other words, two node objects return the same key if and only if isSameNode
indicates that they are the same node.
The returned key value is useful as a key in hashes.
=item nodeValue
$content = $node->nodeValue;
If the node has any content (such as stored in a C<<<<<< text node >>>>>>) it can get requested through this function.
I<<<<<< NOTE: >>>>>> Element Nodes have no content per definition. To get the text value of an
Element use textContent() instead!
=item textContent
$content = $node->textContent;
this function returns the content of all text nodes in the descendants of the
given node as specified in DOM.
=item nodeType
$type = $node->nodeType;
Return a numeric value representing the node type of this node. The module
XML::LibXML by default exports constants for the node types (see the EXPORT
section in the L<<<<<< XML::LibXML >>>>>> manual page).
=item unbindNode
$node->unbindNode();
Unbinds the Node from its siblings and Parent, but not from the Document it
belongs to. If the node is not inserted into the DOM afterwards, it will be
lost after the program terminates. From a low level view, the unbound node is
stripped from the context it is and inserted into a (hidden) document-fragment.
=item removeChild
$childnode = $node->removeChild( $childnode );
This will unbind the Child Node from its parent C<<<<<< $node >>>>>>. The function returns the unbound node. If C<<<<<< $childnode >>>>>> is not a child of the given Node the function will fail.
=item replaceChild
$oldnode = $node->replaceChild( $newNode, $oldNode );
Replaces the C<<<<<< $oldNode >>>>>> with the C<<<<<< $newNode >>>>>>. The C<<<<<< $oldNode >>>>>> will be unbound from the Node. This function differs from the DOM L2
specification, in the case, if the new node is not part of the document, the
node will be imported first.
=item replaceNode
$node->replaceNode($newNode);
This function is very similar to replaceChild(), but it replaces the node
itself rather than a childnode. This is useful if a node found by any XPath
function, should be replaced.
=item appendChild
$childnode = $node->appendChild( $childnode );
The function will add the C<<<<<< $childnode >>>>>> to the end of C<<<<<< $node >>>>>>'s children. The function should fail, if the new childnode is already a child
of C<<<<<< $node >>>>>>. This function differs from the DOM L2 specification, in the case, if the new
node is not part of the document, the node will be imported first.
=item addChild
$childnode = $node->addChild( $childnode );
As an alternative to appendChild() one can use the addChild() function. This
function is a bit faster, because it avoids all DOM conformity checks.
Therefore this function is quite useful if one builds XML documents in memory
where the order and ownership (C<<<<<< ownerDocument >>>>>>) is assured.
addChild() uses libxml2's own xmlAddChild() function. Thus it has to be used
with extra care: If a text node is added to a node and the node itself or its
last childnode is as well a text node, the node to add will be merged with the
one already available. The current node will be removed from memory after this
action. Because perl is not aware of this action, the perl instance is still
available. XML::LibXML will catch the loss of a node and refuse to run any
function called on that node.
my $t1 = $doc->createTextNode( "foo" );
my $t2 = $doc->createTextNode( "bar" );
$t1->addChild( $t2 ); # is OK
my $val = $t2->nodeValue(); # will fail, script dies
Also addChild() will not check if the added node belongs to the same document
as the node it will be added to. This could lead to inconsistent documents and
in more worse cases even to memory violations, if one does not keep track of
this issue.
Although this sounds like a lot of trouble, addChild() is useful if a document
is built from a stream, such as happens sometimes in SAX handlers or filters.
If you are not sure about the source of your nodes, you better stay with
appendChild(), because this function is more user friendly in the sense of
being more error tolerant.
=item addNewChild
$node = $parent->addNewChild( $nsURI, $name );
Similar to C<<<<<< addChild() >>>>>>, this function uses low level libxml2 functionality to provide faster
interface for DOM building. I<<<<<< addNewChild() >>>>>> uses C<<<<<< xmlNewChild() >>>>>> to create a new node on a given parent element.
addNewChild() has two parameters $nsURI and $name, where $nsURI is an
(optional) namespace URI. $name is the fully qualified element name;
addNewChild() will determine the correct prefix if necessary.
The function returns the newly created node.
This function is very useful for DOM building, where a created node can be
directly associated with its parent. I<<<<<< NOTE >>>>>> this function is not part of the DOM specification and its use will limit your
code to XML::LibXML.
=item addSibling
$node->addSibling($newNode);
addSibling() allows adding an additional node to the end of a nodelist, defined
by the given node.
=item cloneNode
$newnode =$node->cloneNode( $deep );
I<<<<<< cloneNode >>>>>> creates a copy of C<<<<<< $node >>>>>>. When $deep is set to 1 (true) the function will copy all child nodes as well.
If $deep is 0 only the current node will be copied. Note that in case of
element, attributes are copied even if $deep is 0.
Note that the behavior of this function for $deep=0 has changed in 1.62 in
order to be consistent with the DOM spec (in older versions attributes and
namespace information was not copied for elements).
I<<<<<< NOTE >>>>>>cloneNode creates a copy of the selected node that includes the parent's
defined I<<<<<< namespaces >>>>>> that are in use by the node (or its children) being cloned. That makes it
useful for extracting a fragment of xml that can be used as a valid xml
document.
=item parentNode
$parentnode = $node->parentNode;
Returns simply the Parent Node of the current node.
=item nextSibling
$nextnode = $node->nextSibling();
Returns the next sibling if any .
=item nextNonBlankSibling
$nextnode = $node->nextNonBlankSibling();
Returns the next non-blank sibling if any (a node is blank if it is a Text or
CDATA node consisting of whitespace only). This method is not defined by DOM.
=item previousSibling
$prevnode = $node->previousSibling();
Analogous to I<<<<<< getNextSibling >>>>>> the function returns the previous sibling if any.
=item previousNonBlankSibling
$prevnode = $node->previousNonBlankSibling();
Returns the previous non-blank sibling if any (a node is blank if it is a Text
or CDATA node consisting of whitespace only). This method is not defined by
DOM.
=item hasChildNodes
$boolean = $node->hasChildNodes();
If the current node has child nodes this function returns TRUE (1), otherwise
it returns FALSE (0, not undef).
=item firstChild
$childnode = $node->firstChild;
If a node has child nodes this function will return the first node in the child
list.
=item lastChild
$childnode = $node->lastChild;
If the C<<<<<< $node >>>>>> has child nodes this function returns the last child node.
=item ownerDocument
$documentnode = $node->ownerDocument;
Through this function it is always possible to access the document the current
node is bound to.
=item getOwner
$node = $node->getOwner;
This function returns the node the current node is associated with. In most
cases this will be a document node or a document fragment node.
=item setOwnerDocument
$node->setOwnerDocument( $doc );
This function binds a node to another DOM. This method unbinds the node first,
if it is already bound to another document.
This function is the opposite calling of L<<<<<< XML::LibXML::Document >>>>>>'s adoptNode() function. Because of this it has the same limitations with
Entity References as adoptNode().
=item insertBefore
$node->insertBefore( $newNode, $refNode );
The method inserts C<<<<<< $newNode >>>>>> before C<<<<<< $refNode >>>>>>. If C<<<<<< $refNode >>>>>> is undefined, the newNode will be set as the new last child of the parent node.
This function differs from the DOM L2 specification, in the case, if the new
node is not part of the document, the node will be imported first,
automatically.
$refNode has to be passed to the function even if it is undefined:
$node->insertBefore( $newNode, undef ); # the same as $node->appendChild( $newNode );
$node->insertBefore( $newNode ); # wrong
Note, that the reference node has to be a direct child of the node the function
is called on. Also, $newChild is not allowed to be an ancestor of the new
parent node.
=item insertAfter
$node->insertAfter( $newNode, $refNode );
The method inserts C<<<<<< $newNode >>>>>> after C<<<<<< $refNode >>>>>>. If C<<<<<< $refNode >>>>>> is undefined, the newNode will be set as the new last child of the parent node.
Note, that $refNode has to be passed explicitly even if it is undef.
=item findnodes
@nodes = $node->findnodes( $xpath_expression );
I<<<<<< findnodes >>>>>> evaluates the xpath expression (XPath 1.0) on the current node and returns the
resulting node set as an array. In scalar context, returns an L<<<<<< XML::LibXML::NodeList >>>>>> object.
The xpath expression can be passed either as a string, or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
I<<<<<< NOTE ON NAMESPACES AND XPATH >>>>>>:
A common mistake about XPath is to assume that node tests consisting of an
element name with no prefix match elements in the default namespace. This
assumption is wrong - by XPath specification, such node tests can only match
elements that are in no (i.e. null) namespace.
So, for example, one cannot match the root element of an XHTML document with C<<<<<< $node-Efind('/html') >>>>>> since C<<<<<< '/html' >>>>>> would only match if the root element C<<<<<< EhtmlE >>>>>> had no namespace, but all XHTML elements belong to the namespace
http://www.w3.org/1999/xhtml. (Note that C<<<<<< xmlns="..." >>>>>> namespace declarations can also be specified in a DTD, which makes the
situation even worse, since the XML document looks as if there was no default
namespace).
There are several possible ways to deal with namespaces in XPath:
=over 4
=item *
The recommended way is to use the L<<<<<< XML::LibXML::XPathContext >>>>>> module to define an explicit context for XPath evaluation, in which a document
independent prefix-to-namespace mapping can be defined. For example:
my $xpc = XML::LibXML::XPathContext->new;
$xpc->registerNs('x', 'http://www.w3.org/1999/xhtml');
$xpc->find('/x:html',$node);
=item *
Another possibility is to use prefixes declared in the queried document (if
known). If the document declares a prefix for the namespace in question (and
the context node is in the scope of the declaration), C<<<<<< XML::LibXML >>>>>> allows you to use the prefix in the XPath expression, e.g.:
$node->find('/x:html');
=back
See also XML::LibXML::XPathContext->findnodes.
=item find
$result = $node->find( $xpath );
I<<<<<< find >>>>>> evaluates the XPath 1.0 expression using the current node as the context of the
expression, and returns the result depending on what type of result the XPath
expression had. For example, the XPath "1 * 3 + 52" results in a L<<<<<< XML::LibXML::Number >>>>>> object being returned. Other expressions might return an L<<<<<< XML::LibXML::Boolean >>>>>> object, or an L<<<<<< XML::LibXML::Literal >>>>>> object (a string). Each of those objects uses Perl's overload feature to "do
the right thing" in different contexts.
The xpath expression can be passed either as a string, or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
See also L<<<<<< XML::LibXML::XPathContext >>>>>>->find.
=item findvalue
print $node->findvalue( $xpath );
I<<<<<< findvalue >>>>>> is exactly equivalent to:
$node->find( $xpath )->to_literal;
That is, it returns the literal value of the results. This enables you to
ensure that you get a string back from your search, allowing certain shortcuts.
This could be used as the equivalent of XSLT's .
See also L<<<<<< XML::LibXML::XPathContext >>>>>>->findvalue.
The xpath expression can be passed either as a string, or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
=item exists
$bool = $node->exists( $xpath_expression );
This method behaves like I<<<<<< findnodes >>>>>>, except that it only returns a boolean value (1 if the expression matches a
node, 0 otherwise) and may be faster than I<<<<<< findnodes >>>>>>, because the XPath evaluation may stop early on the first match (this is true
for libxml2 >= 2.6.27).
For XPath expressions that do not return node-set, the method returns true if
the returned value is a non-zero number or a non-empty string.
=item childNodes
@childnodes = $node->childNodes();
I<<<<<< childNodes >>>>>> implements a more intuitive interface to the childnodes of the current node. It
enables you to pass all children directly to a C<<<<<< map >>>>>> or C<<<<<< grep >>>>>>. If this function is called in scalar context, a L<<<<<< XML::LibXML::NodeList >>>>>> object will be returned.
=item nonBlankChildNodes
@childnodes = $node->nonBlankChildNodes();
This is like I<<<<<< childNodes >>>>>>, but returns only non-blank nodes (where a node is blank if it is a Text or
CDATA node consisting of whitespace only). This method is not defined by DOM.
=item toString
$xmlstring = $node->toString($format,$docencoding);
This method is similar to the method C<<<<<< toString >>>>>> of a L<<<<<< XML::LibXML::Document >>>>>> but for a single node. It returns a string consisting of XML serialization of
the given node and all its descendants. Unlike C<<<<<< XML::LibXML::Document::toString >>>>>>, in this case the resulting string is by default a character string (UTF-8
encoded with UTF8 flag on). An optional flag $format controls indentation, as
in C<<<<<< XML::LibXML::Document::toString >>>>>>. If the second optional $docencoding flag is true, the result will be a byte
string in the document encoding (see C<<<<<< XML::LibXML::Document::actualEncoding >>>>>>).
=item toStringC14N
$c14nstring = $node->toStringC14N();
$c14nstring = $node->toStringC14N($with_comments, $xpath_expression , $xpath_context);
The function is similar to toString(). Instead of simply serializing the
document tree, it transforms it as it is specified in the XML-C14N
Specification (see L<<<<<< http://www.w3.org/TR/xml-c14n >>>>>>). Such transformation is known as canonization.
If $with_comments is 0 or not defined, the result-document will not contain any
comments that exist in the original document. To include comments into the
canonized document, $with_comments has to be set to 1.
The parameter $xpath_expression defines the nodeset of nodes that should be
visible in the resulting document. This can be used to filter out some nodes.
One has to note, that only the nodes that are part of the nodeset, will be
included into the result-document. Their child-nodes will not exist in the
resulting document, unless they are part of the nodeset defined by the xpath
expression.
If $xpath_expression is omitted or empty, toStringC14N() will include all nodes
in the given sub-tree, using the following XPath expressions: with comments
(. | .//node() | .//@* | .//namespace::*)
and without comments
(. | .//node() | .//@* | .//namespace::*)[not(self::comment())]
An optional parameter $xpath_context can be used to pass an L<<<<<< XML::LibXML::XPathContext >>>>>> object defining the context for evaluation of $xpath_expression. This is useful
for mapping namespace prefixes used in the XPath expression to namespace URIs.
Note, however, that $node will be used as the context node for the evaluation,
not the context node of $xpath_context!
=item toStringC14N_v1_1
$c14nstring = $node->toStringC14N_v1_1();
$c14nstring = $node->toStringC14N_v1_1($with_comments, $xpath_expression , $xpath_context);
This function behaves like toStringC14N() except that it uses the
"XML_C14N_1_1" constant for canonicalising using the "C14N 1.1 spec".
=item toStringEC14N
$ec14nstring = $node->toStringEC14N();
$ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $inclusive_prefix_list);
$ec14nstring = $node->toStringEC14N($with_comments, $xpath_expression, $xpath_context, $inclusive_prefix_list);
The function is similar to toStringC14N() but follows the XML-EXC-C14N
Specification (see L<<<<<< http://www.w3.org/TR/xml-exc-c14n >>>>>>) for exclusive canonization of XML.
The arguments $with_comments, $xpath_expression, $xpath_context are as in
toStringC14N(). An ARRAY reference can be passed as the last argument
$inclusive_prefix_list, listing namespace prefixes that are to be handled in
the manner described by the Canonical XML Recommendation (i.e. preserved in the
output even if the namespace is not used). C.f. the spec for details.
=item serialize
$str = $doc->serialize($format);
An alias for toString(). This function was name added to be more consistent
with libxml2.
=item serialize_c14n
An alias for toStringC14N().
=item serialize_exc_c14n
An alias for toStringEC14N().
=item localname
$localname = $node->localname;
Returns the local name of a tag. This is the part behind the colon.
=item prefix
$nameprefix = $node->prefix;
Returns the prefix of a tag. This is the part before the colon.
=item namespaceURI
$uri = $node->namespaceURI();
returns the URI of the current namespace.
=item hasAttributes
$boolean = $node->hasAttributes();
returns 1 (TRUE) if the current node has any attributes set, otherwise 0
(FALSE) is returned.
=item attributes
@attributelist = $node->attributes();
This function returns all attributes and namespace declarations assigned to the
given node.
Because XML::LibXML does not implement namespace declarations and attributes
the same way, it is required to test what kind of node is handled while
accessing the functions result.
If this function is called in array context the attribute nodes are returned as
an array. In scalar context, the function will return a L<<<<<< XML::LibXML::NamedNodeMap >>>>>> object.
=item lookupNamespaceURI
$URI = $node->lookupNamespaceURI( $prefix );
Find a namespace URI by its prefix starting at the current node.
=item lookupNamespacePrefix
$prefix = $node->lookupNamespacePrefix( $URI );
Find a namespace prefix by its URI starting at the current node.
I<<<<<< NOTE >>>>>> Only the namespace URIs are meant to be unique. The prefix is only document
related. Also the document might have more than a single prefix defined for a
namespace.
=item normalize
$node->normalize;
This function normalizes adjacent text nodes. This function is not as strict as
libxml2's xmlTextMerge() function, since it will not free a node that is still
referenced by the perl layer.
=item getNamespaces
@nslist = $node->getNamespaces;
If a node has any namespaces defined, this function will return these
namespaces. Note, that this will not return all namespaces that are in scope,
but only the ones declared explicitly for that node.
Although getNamespaces is available for all nodes, it only makes sense if used
with element nodes.
=item removeChildNodes
$node->removeChildNodes();
This function is not specified for any DOM level: It removes all childnodes
from a node in a single step. Other than the libxml2 function itself
(xmlFreeNodeList), this function will not immediately remove the nodes from the
memory. This saves one from getting memory violations, if there are nodes still
referred to from the Perl level.
=item baseURI ()
$strURI = $node->baseURI();
Searches for the base URL of the node. The method should work on both XML and
HTML documents even if base mechanisms for these are completely different. It
returns the base as defined in RFC 2396 sections "5.1.1. Base URI within
Document Content" and "5.1.2. Base URI from the Encapsulating Entity". However
it does not return the document base (5.1.3), use method C<<<<<< URI >>>>>> of C<<<<<< XML::LibXML::Document >>>>>> for this.
=item setBaseURI ($strURI)
$node->setBaseURI($strURI);
This method only does something useful for an element node in an XML document.
It sets the xml:base attribute on the node to $strURI, which effectively sets
the base URI of the node to the same value.
Note: For HTML documents this behaves as if the document was XML which may not
be desired, since it does not effectively set the base URI of the node. See RFC
2396 appendix D for an example of how base URI can be specified in HTML.
=item nodePath
$node->nodePath();
This function is not specified for any DOM level: It returns a canonical
structure based XPath for a given node.
=item line_number
$lineno = $node->line_number();
This function returns the line number where the tag was found during parsing.
If a node is added to the document the line number is 0. Problems may occur, if
a node from one document is passed to another one.
IMPORTANT: Due to limitations in the libxml2 library line numbers greater than
65535 will be returned as 65535. Please see L<<<<<< http://bugzilla.gnome.org/show_bug.cgi?id=325533 >>>>>> for more details.
Note: line_number() is special to XML::LibXML and not part of the DOM
specification.
If the line_numbers flag of the parser was not activated before parsing,
line_number() will always return 0.
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\m"
"
LibXML/Namespace.podnu 6$ =head1 NAME
XML::LibXML::Namespace - XML::LibXML Namespace Implementation
=head1 SYNOPSIS
use XML::LibXML;
# Only methods specific to Namespace nodes are listed here,
# see the XML::LibXML::Node manpage for other methods
my $ns = XML::LibXML::Namespace->new($nsURI);
print $ns->nodeName();
print $ns->name();
$localname = $ns->getLocalName();
print $ns->getData();
print $ns->getValue();
print $ns->value();
$known_uri = $ns->getNamespaceURI();
$known_prefix = $ns->getPrefix();
$key = $ns->unique_key();
=head1 DESCRIPTION
Namespace nodes are returned by both $element->findnodes('namespace::foo') or
by $node->getNamespaces().
The namespace node API is not part of any current DOM API, and so it is quite
minimal. It should be noted that namespace nodes are I<<<<<< not >>>>>> a sub class of L<<<<<< XML::LibXML::Node >>>>>>, however Namespace nodes act a lot like attribute nodes, and similarly named
methods will return what you would expect if you treated the namespace node as
an attribute. Note that in order to fix several inconsistencies between the API
and the documentation, the behavior of some functions have been changed in
1.64.
=head1 METHODS
=over 4
=item new
my $ns = XML::LibXML::Namespace->new($nsURI);
Creates a new Namespace node. Note that this is not a 'node' as an attribute or
an element node. Therefore you can't do call all L<<<<<< XML::LibXML::Node >>>>>> Functions. All functions available for this node are listed below.
Optionally you can pass the prefix to the namespace constructor. If this second
parameter is omitted you will create a so called default namespace. Note, the
newly created namespace is not bound to any document or node, therefore you
should not expect it to be available in an existing document.
=item declaredURI
Returns the URI for this namespace.
=item declaredPrefix
Returns the prefix for this namespace.
=item nodeName
print $ns->nodeName();
Returns "xmlns:prefix", where prefix is the prefix for this namespace.
=item name
print $ns->name();
Alias for nodeName()
=item getLocalName
$localname = $ns->getLocalName();
Returns the local name of this node as if it were an attribute, that is, the
prefix associated with the namespace.
=item getData
print $ns->getData();
Returns the URI of the namespace, i.e. the value of this node as if it were an
attribute.
=item getValue
print $ns->getValue();
Alias for getData()
=item value
print $ns->value();
Alias for getData()
=item getNamespaceURI
$known_uri = $ns->getNamespaceURI();
Returns the string "http://www.w3.org/2000/xmlns/"
=item getPrefix
$known_prefix = $ns->getPrefix();
Returns the string "xmlns"
=item unique_key
$key = $ns->unique_key();
This method returns a key guaranteed to be unique for this namespace, and to
always be the same value for this namespace. Two namespace objects return the
same key if and only if they have the same prefix and the same URI. The
returned key value is useful as a key in hashes.
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\>8%o %o LibXML/Parser.podnu 6$ =head1 NAME
XML::LibXML::Parser - Parsing XML Data with XML::LibXML
=head1 SYNOPSIS
use XML::LibXML '1.70';
# Parser constructor
$parser = XML::LibXML->new();
$parser = XML::LibXML->new(option=>value, ...);
$parser = XML::LibXML->new({option=>value, ...});
# Parsing XML
$dom = XML::LibXML->load_xml(
location => $file_or_url
# parser options ...
);
$dom = XML::LibXML->load_xml(
string => $xml_string
# parser options ...
);
$dom = XML::LibXML->load_xml(
string => (\$xml_string)
# parser options ...
);
$dom = XML::LibXML->load_xml({
IO => $perl_file_handle
# parser options ...
);
$dom = $parser->load_xml(...);
# Parsing HTML
$dom = XML::LibXML->load_html(...);
$dom = $parser->load_html(...);
# Parsing well-balanced XML chunks
$fragment = $parser->parse_balanced_chunk( $wbxmlstring, $encoding );
# Processing XInclude
$parser->process_xincludes( $doc );
$parser->processXIncludes( $doc );
# Old-style parser interfaces
$doc = $parser->parse_file( $xmlfilename );
$doc = $parser->parse_fh( $io_fh );
$doc = $parser->parse_string( $xmlstring);
$doc = $parser->parse_html_file( $htmlfile, \%opts );
$doc = $parser->parse_html_fh( $io_fh, \%opts );
$doc = $parser->parse_html_string( $htmlstring, \%opts );
# Push parser
$parser->parse_chunk($string, $terminate);
$parser->init_push();
$parser->push(@data);
$doc = $parser->finish_push( $recover );
# Set/query parser options
$parser->option_exists($name);
$parser->get_option($name);
$parser->set_option($name,$value);
$parser->set_options({$name=>$value,...});
# XML catalogs
$parser->load_catalog( $catalog_file );
=head1 PARSING
An XML document is read into a data structure such as a DOM tree by a piece of
software, called a parser. XML::LibXML currently provides four different parser
interfaces:
=over 4
=item *
A DOM Pull-Parser
=item *
A DOM Push-Parser
=item *
A SAX Parser
=item *
A DOM based SAX Parser.
=back
=head2 Creating a Parser Instance
XML::LibXML provides an OO interface to the libxml2 parser functions. Thus you
have to create a parser instance before you can parse any XML data.
=over 4
=item new
$parser = XML::LibXML->new();
$parser = XML::LibXML->new(option=>value, ...);
$parser = XML::LibXML->new({option=>value, ...});
Create a new XML and HTML parser instance. Each parser instance holds default
values for various parser options. Optionally, one can pass a hash reference or
a list of option => value pairs to set a different default set of options.
Unless specified otherwise, the options C<<<<<< load_ext_dtd >>>>>>, and C<<<<<< expand_entities >>>>>> are set to 1. See L<<<<<< Parser Options >>>>>> for a list of libxml2 parser's options.
=back
=head2 DOM Parser
One of the common parser interfaces of XML::LibXML is the DOM parser. This
parser reads XML data into a DOM like data structure, so each tag can get
accessed and transformed.
XML::LibXML's DOM parser is not only capable to parse XML data, but also
(strict) HTML files. There are three ways to parse documents - as a string, as
a Perl filehandle, or as a filename/URL. The return value from each is a L<<<<<< XML::LibXML::Document >>>>>> object, which is a DOM object.
All of the functions listed below will throw an exception if the document is
invalid. To prevent this causing your program exiting, wrap the call in an
eval{} block
=over 4
=item load_xml
$dom = XML::LibXML->load_xml(
location => $file_or_url
# parser options ...
);
$dom = XML::LibXML->load_xml(
string => $xml_string
# parser options ...
);
$dom = XML::LibXML->load_xml(
string => (\$xml_string)
# parser options ...
);
$dom = XML::LibXML->load_xml({
IO => $perl_file_handle
# parser options ...
);
$dom = $parser->load_xml(...);
This function is available since XML::LibXML 1.70. It provides easy to use
interface to the XML parser that parses given file (or non-HTTPS URL), string,
or input stream to a DOM tree. The arguments can be passed in a HASH reference
or as name => value pairs. The function can be called as a class method or an
object method. In both cases it internally creates a new parser instance
passing the specified parser options; if called as an object method, it clones
the original parser (preserving its settings) and additionally applies the
specified options to the new parser. See the constructor C<<<<<< new >>>>>> and L<<<<<< Parser Options >>>>>> for more information.
Note that, due to a limitation in the underlying libxml2 library, this call
does not recognize HTTPS-based URLs. (It will treat an HTTPS URL as a filename,
likely throwing a "No such file or directory" exception.)
=item load_html
$dom = XML::LibXML->load_html(...);
$dom = $parser->load_html(...);
This function is available since XML::LibXML 1.70. It has the same usage as C<<<<<< load_xml >>>>>>, providing interface to the HTML parser. See C<<<<<< load_xml >>>>>> for more information.
=back
Parsing HTML may cause problems, especially if the ampersand ('&') is used.
This is a common problem if HTML code is parsed that contains links to
CGI-scripts. Such links cause the parser to throw errors. In such cases libxml2
still parses the entire document as there was no error, but the error causes
XML::LibXML to stop the parsing process. However, the document is not lost.
Such HTML documents should be parsed using the I<<<<<< recover >>>>>> flag. By default recovering is deactivated.
The functions described above are implemented to parse well formed documents.
In some cases a program gets well balanced XML instead of well formed documents
(e.g. an XML fragment from a database). With XML::LibXML it is not required to
wrap such fragments in the code, because XML::LibXML is capable even to parse
well balanced XML fragments.
=over 4
=item parse_balanced_chunk
$fragment = $parser->parse_balanced_chunk( $wbxmlstring, $encoding );
This function parses a well balanced XML string into a L<<<<<< XML::LibXML::DocumentFragment >>>>>>. The first arguments contains the input string, the optional second argument
can be used to specify character encoding of the input (UTF-8 is assumed by
default).
=item parse_xml_chunk
This is the old name of parse_balanced_chunk(). Because it may causes confusion
with the push parser interface, this function should not be used anymore.
=back
By default XML::LibXML does not process XInclude tags within an XML Document
(see options section below). XML::LibXML allows one to post-process a document
to expand XInclude tags.
=over 4
=item process_xincludes
$parser->process_xincludes( $doc );
After a document is parsed into a DOM structure, you may want to expand the
documents XInclude tags. This function processes the given document structure
and expands all XInclude tags (or throws an error) by using the flags and
callbacks of the given parser instance.
Note that the resulting Tree contains some extra nodes (of type
XML_XINCLUDE_START and XML_XINCLUDE_END) after successfully processing the
document. These nodes indicate where data was included into the original tree.
if the document is serialized, these extra nodes will not show up.
Remember: A Document with processed XIncludes differs from the original
document after serialization, because the original XInclude tags will not get
restored!
If the parser flag "expand_xincludes" is set to 1, you need not to post process
the parsed document.
=item processXIncludes
$parser->processXIncludes( $doc );
This is an alias to process_xincludes, but through a JAVA like function name.
=item parse_file
$doc = $parser->parse_file( $xmlfilename );
This function parses an XML document from a file or network; $xmlfilename can
be either a filename or a (non-HTTPS) URL. Note that for parsing files, this
function is the fastest choice, about 6-8 times faster then parse_fh().
=item parse_fh
$doc = $parser->parse_fh( $io_fh );
parse_fh() parses a IOREF or a subclass of IO::Handle.
Because the data comes from an open handle, libxml2's parser does not know
about the base URI of the document. To set the base URI one should use
parse_fh() as follows:
my $doc = $parser->parse_fh( $io_fh, $baseuri );
=item parse_string
$doc = $parser->parse_string( $xmlstring);
This function is similar to parse_fh(), but it parses an XML document that is
available as a single string in memory, or alternatively as a reference to a
scalar containing a string. Again, you can pass an optional base URI to the
function.
my $doc = $parser->parse_string( $xmlstring, $baseuri );
my $doc = $parser->parse_string(\$xmlstring, $baseuri);
=item parse_html_file
$doc = $parser->parse_html_file( $htmlfile, \%opts );
Similar to parse_file() but parses HTML (strict) documents; $htmlfile can be
filename or (non-HTTPS) URL.
An optional second argument can be used to pass some options to the HTML parser
as a HASH reference. See options labeled with HTML in L<<<<<< Parser Options >>>>>>.
=item parse_html_fh
$doc = $parser->parse_html_fh( $io_fh, \%opts );
Similar to parse_fh() but parses HTML (strict) streams.
An optional second argument can be used to pass some options to the HTML parser
as a HASH reference. See options labeled with HTML in L<<<<<< Parser Options >>>>>>.
Note: encoding option may not work correctly with this function in libxml2 <
2.6.27 if the HTML file declares charset using a META tag.
=item parse_html_string
$doc = $parser->parse_html_string( $htmlstring, \%opts );
Similar to parse_string() but parses HTML (strict) strings.
An optional second argument can be used to pass some options to the HTML parser
as a HASH reference. See options labeled with HTML in L<<<<<< Parser Options >>>>>>.
=back
=head2 Push Parser
XML::LibXML provides a push parser interface. Rather than pulling the data from
a given source the push parser waits for the data to be pushed into it.
This allows one to parse large documents without waiting for the parser to
finish. The interface is especially useful if a program needs to pre-process
the incoming pieces of XML (e.g. to detect document boundaries).
While XML::LibXML parse_*() functions force the data to be a well-formed XML,
the push parser will take any arbitrary string that contains some XML data. The
only requirement is that all the pushed strings are together a well formed
document. With the push parser interface a program can interrupt the parsing
process as required, where the parse_*() functions give not enough flexibility.
Different to the pull parser implemented in parse_fh() or parse_file(), the
push parser is not able to find out about the documents end itself. Thus the
calling program needs to indicate explicitly when the parsing is done.
In XML::LibXML this is done by a single function:
=over 4
=item parse_chunk
$parser->parse_chunk($string, $terminate);
parse_chunk() tries to parse a given chunk of data, which isn't necessarily
well balanced data. The function takes two parameters: The chunk of data as a
string and optional a termination flag. If the termination flag is set to a
true value (e.g. 1), the parsing will be stopped and the resulting document
will be returned as the following example describes:
my $parser = XML::LibXML->new;
for my $string ( "<", "foo", ' bar="hello world"', "/>") {
$parser->parse_chunk( $string );
}
my $doc = $parser->parse_chunk("", 1); # terminate the parsing
=back
Internally XML::LibXML provides three functions that control the push parser
process:
=over 4
=item init_push
$parser->init_push();
Initializes the push parser.
=item push
$parser->push(@data);
This function pushes the data stored inside the array to libxml2's parser. Each
entry in @data must be a normal scalar! This method can be called repeatedly.
=item finish_push
$doc = $parser->finish_push( $recover );
This function returns the result of the parsing process. If this function is
called without a parameter it will complain about non well-formed documents. If
$restore is 1, the push parser can be used to restore broken or non well formed
(XML) documents as the following example shows:
eval {
$parser->push( "", "bar" );
$doc = $parser->finish_push(); # will report broken XML
};
if ( $@ ) {
# ...
}
This can be annoying if the closing tag is missed by accident. The following
code will restore the document:
eval {
$parser->push( "", "bar" );
$doc = $parser->finish_push(1); # will return the data parsed
# unless an error happened
};
print $doc->toString(); # returns "bar"
Of course finish_push() will return nothing if there was no data pushed to the
parser before.
=back
=head2 Pull Parser (Reader)
XML::LibXML also provides a pull-parser interface similar to the XmlReader
interface in .NET. This interface is almost streaming, and is usually faster
and simpler to use than SAX. See L<<<<<< XML::LibXML::Reader >>>>>>.
=head2 Direct SAX Parser
XML::LibXML provides a direct SAX parser in the L<<<<<< XML::LibXML::SAX >>>>>> module.
=head2 DOM based SAX Parser
XML::LibXML also provides a DOM based SAX parser. The SAX parser is defined in
the module XML::LibXML::SAX::Parser. As it is not a stream based parser, it
parses documents into a DOM and traverses the DOM tree instead.
The API of this parser is exactly the same as any other Perl SAX2 parser. See
XML::SAX::Intro for details.
Aside from the regular parsing methods, you can access the DOM tree traverser
directly, using the generate() method:
my $doc = build_yourself_a_document();
my $saxparser = $XML::LibXML::SAX::Parser->new( ... );
$parser->generate( $doc );
This is useful for serializing DOM trees, for example that you might have done
prior processing on, or that you have as a result of XSLT processing.
I<<<<<< WARNING >>>>>>
This is NOT a streaming SAX parser. As I said above, this parser reads the
entire document into a DOM and serialises it. Some people couldn't read that in
the paragraph above so I've added this warning. If you want a streaming SAX
parser look at the L<<<<<< XML::LibXML::SAX >>>>>> man page
=head1 SERIALIZATION
XML::LibXML provides some functions to serialize nodes and documents. The
serialization functions are described on the L<<<<<< XML::LibXML::Node >>>>>> manpage or the L<<<<<< XML::LibXML::Document >>>>>> manpage. XML::LibXML checks three global flags that alter the serialization
process:
=over 4
=item *
skipXMLDeclaration
=item *
skipDTD
=item *
setTagCompression
=back
of that three functions only setTagCompression is available for all
serialization functions.
Because XML::LibXML does these flags not itself, one has to define them locally
as the following example shows:
local $XML::LibXML::skipXMLDeclaration = 1;
local $XML::LibXML::skipDTD = 1;
local $XML::LibXML::setTagCompression = 1;
If skipXMLDeclaration is defined and not '0', the XML declaration is omitted
during serialization.
If skipDTD is defined and not '0', an existing DTD would not be serialized with
the document.
If setTagCompression is defined and not '0' empty tags are displayed as open
and closing tags rather than the shortcut. For example the empty tag I<<<<<< foo >>>>>> will be rendered as I<<<<<< EfooEE/fooE >>>>>> rather than I<<<<<< Efoo/E >>>>>>.
=head1 PARSER OPTIONS
Handling of libxml2 parser options has been unified and improved in XML::LibXML
1.70. You can now set default options for a particular parser instance by
passing them to the constructor as C<<<<<< XML::LibXML-Enew({name=Evalue, ...}) >>>>>> or C<<<<<< XML::LibXML-Enew(name=Evalue,...) >>>>>>. The options can be queried and changed using the following methods (pre-1.70
interfaces such as C<<<<<< $parser-Eload_ext_dtd(0) >>>>>> also exist, see below):
=over 4
=item option_exists
$parser->option_exists($name);
Returns 1 if the current XML::LibXML version supports the option C<<<<<< $name >>>>>>, otherwise returns 0 (note that this does not necessarily mean that the option
is supported by the underlying libxml2 library).
=item get_option
$parser->get_option($name);
Returns the current value of the parser option C<<<<<< $name >>>>>>.
=item set_option
$parser->set_option($name,$value);
Sets option C<<<<<< $name >>>>>> to value C<<<<<< $value >>>>>>.
=item set_options
$parser->set_options({$name=>$value,...});
Sets multiple parsing options at once.
=back
IMPORTANT NOTE: This documentation reflects the parser flags available in
libxml2 2.7.3. Some options have no effect if an older version of libxml2 is
used.
Each of the flags listed below is labeled
=over 4
=item /parser/
if it can be used with a C<<<<<< XML::LibXML >>>>>> parser object (i.e. passed to C<<<<<< XML::LibXML-Enew >>>>>>, C<<<<<< XML::LibXML-Eset_option >>>>>>, etc.)
=item /html/
if it can be used passed to the C<<<<<< parse_html_* >>>>>> methods
=item /reader/
if it can be used with the C<<<<<< XML::LibXML::Reader >>>>>>.
=back
Unless specified otherwise, the default for boolean valued options is 0
(false).
The available options are:
=over 4
=item URI
/parser, html, reader/
In case of parsing strings or file handles, XML::LibXML doesn't know about the
base uri of the document. To make relative references such as XIncludes work,
one has to set a base URI, that is then used for the parsed document.
=item line_numbers
/parser, html, reader/
If this option is activated, libxml2 will store the line number of each element
node in the parsed document. The line number can be obtained using the C<<<<<< line_number() >>>>>> method of the C<<<<<< XML::LibXML::Node >>>>>> class (for non-element nodes this may report the line number of the containing
element). The line numbers are also used for reporting positions of validation
errors.
IMPORTANT: Due to limitations in the libxml2 library line numbers greater than
65535 will be returned as 65535. Unfortunately, this is a long and sad story,
please see L<<<<<< http://bugzilla.gnome.org/show_bug.cgi?id=325533 >>>>>> for more details.
=item encoding
/html/
character encoding of the input
=item recover
/parser, html, reader/
recover from errors; possible values are 0, 1, and 2
A true value turns on recovery mode which allows one to parse broken XML or
HTML data. The recovery mode allows the parser to return the successfully
parsed portion of the input document. This is useful for almost well-formed
documents, where for example a closing tag is missing somewhere. Still,
XML::LibXML will only parse until the first fatal (non-recoverable) error
occurs, reporting recoverable parsing errors as warnings. To suppress even
these warnings, use recover=>2.
Note that validation is switched off automatically in recovery mode.
=item expand_entities
/parser, reader/
substitute entities; possible values are 0 and 1; default is 1
Note that although this flag disables entity substitution, it does not prevent
the parser from loading external entities; when substitution of an external
entity is disabled, the entity will be represented in the document tree by an
XML_ENTITY_REF_NODE node whose subtree will be the content obtained by parsing
the external resource; Although this nesting is visible from the DOM it is
transparent to XPath data model, so it is possible to match nodes in an
unexpanded entity by the same XPath expression as if the entity were expanded.
See also ext_ent_handler.
=item ext_ent_handler
/parser/
Provide a custom external entity handler to be used when expand_entities is set
to 1. Possible value is a subroutine reference.
This feature does not work properly in libxml2 < 2.6.27!
The subroutine provided is called whenever the parser needs to retrieve the
content of an external entity. It is called with two arguments: the system ID
(URI) and the public ID. The value returned by the subroutine is parsed as the
content of the entity.
This method can be used to completely disable entity loading, e.g. to prevent
exploits of the type described at (L<<<<<< http://searchsecuritychannel.techtarget.com/generic/0,295582,sid97_gci1304703,00.html >>>>>>), where a service is tricked to expose its private data by letting it parse a
remote file (RSS feed) that contains an entity reference to a local file (e.g. C<<<<<< /etc/fstab >>>>>>).
A more granular solution to this problem, however, is provided by custom URL
resolvers, as in
my $c = XML::LibXML::InputCallback->new();
sub match { # accept file:/ URIs except for XML catalogs in /etc/xml/
my ($uri) = @_;
return ($uri=~m{^file:/}
and $uri !~ m{^file:///etc/xml/})
? 1 : 0;
}
$c->register_callbacks([ \&match, sub{}, sub{}, sub{} ]);
$parser->input_callbacks($c);
=item load_ext_dtd
/parser, reader/
load the external DTD subset while parsing; possible values are 0 and 1. Unless
specified, XML::LibXML sets this option to 1.
This flag is also required for DTD Validation, to provide complete attribute,
and to expand entities, regardless if the document has an internal subset. Thus
switching off external DTD loading, will disable entity expansion, validation,
and complete attributes on internal subsets as well.
=item complete_attributes
/parser, reader/
create default DTD attributes; possible values are 0 and 1
=item validation
/parser, reader/
validate with the DTD; possible values are 0 and 1
=item suppress_errors
/parser, html, reader/
suppress error reports; possible values are 0 and 1
=item suppress_warnings
/parser, html, reader/
suppress warning reports; possible values are 0 and 1
=item pedantic_parser
/parser, html, reader/
pedantic error reporting; possible values are 0 and 1
=item no_blanks
/parser, html, reader/
remove blank nodes; possible values are 0 and 1
=item no_defdtd
/html/
do not add a default DOCTYPE; possible values are 0 and 1
the default is (0) to add a DTD when the input html lacks one
=item expand_xinclude or xinclude
/parser, reader/
Implement XInclude substitution; possible values are 0 and 1
Expands XInclude tags immediately while parsing the document. Note that the
parser will use the URI resolvers installed via C<<<<<< XML::LibXML::InputCallback >>>>>> to parse the included document (if any).
=item no_xinclude_nodes
/parser, reader/
do not generate XINCLUDE START/END nodes; possible values are 0 and 1
=item no_network
/parser, html, reader/
Forbid network access; possible values are 0 and 1
If set to true, all attempts to fetch non-local resources (such as DTD or
external entities) will fail (unless custom callbacks are defined).
It may be necessary to use the flag C<<<<<< recover >>>>>> for processing documents requiring such resources while networking is off.
=item clean_namespaces
/parser, reader/
remove redundant namespaces declarations during parsing; possible values are 0
and 1.
=item no_cdata
/parser, html, reader/
merge CDATA as text nodes; possible values are 0 and 1
=item no_basefix
/parser, reader/
not fixup XINCLUDE xml#base URIS; possible values are 0 and 1
=item huge
/parser, html, reader/
relax any hardcoded limit from the parser; possible values are 0 and 1. Unless
specified, XML::LibXML sets this option to 0.
Note: the default value for this option was changed to protect against denial
of service through entity expansion attacks. Before enabling the option ensure
you have taken alternative measures to protect your application against this
type of attack.
=item gdome
/parser/
THIS OPTION IS EXPERIMENTAL!
Although quite powerful, XML::LibXML's DOM implementation is incomplete with
respect to the DOM level 2 or level 3 specifications. XML::GDOME is based on
libxml2 as well, and provides a rather complete DOM implementation by wrapping
libgdome. This flag allows you to make use of XML::LibXML's full parser options
and XML::GDOME's DOM implementation at the same time.
To make use of this function, one has to install libgdome and configure
XML::LibXML to use this library. For this you need to rebuild XML::LibXML!
Note: this feature was not seriously tested in recent XML::LibXML releases.
=back
For compatibility with XML::LibXML versions prior to 1.70, the following
methods are also supported for querying and setting the corresponding parser
options (if called without arguments, the methods return the current value of
the corresponding parser options; with an argument sets the option to a given
value):
$parser->validation();
$parser->recover();
$parser->pedantic_parser();
$parser->line_numbers();
$parser->load_ext_dtd();
$parser->complete_attributes();
$parser->expand_xinclude();
$parser->gdome_dom();
$parser->clean_namespaces();
$parser->no_network();
The following obsolete methods trigger parser options in some special way:
=over 4
=item recover_silently
$parser->recover_silently(1);
If called without an argument, returns true if the current value of the C<<<<<< recover >>>>>> parser option is 2 and returns false otherwise. With a true argument sets the C<<<<<< recover >>>>>> parser option to 2; with a false argument sets the C<<<<<< recover >>>>>> parser option to 0.
=item expand_entities
$parser->expand_entities(0);
Get/set the C<<<<<< expand_entities >>>>>> option. If called with a true argument, also turns the C<<<<<< load_ext_dtd >>>>>> option to 1.
=item keep_blanks
$parser->keep_blanks(0);
This is actually the opposite of the C<<<<<< no_blanks >>>>>> parser option. If used without an argument retrieves negated value of C<<<<<< no_blanks >>>>>>. If used with an argument sets C<<<<<< no_blanks >>>>>> to the opposite value.
=item base_uri
$parser->base_uri( $your_base_uri );
Get/set the C<<<<<< URI >>>>>> option.
=back
=head1 XML CATALOGS
C<<<<<< libxml2 >>>>>> supports XML catalogs. Catalogs are used to map remote resources to their local
copies. Using catalogs can speed up parsing processes if many external
resources from remote addresses are loaded into the parsed documents (such as
DTDs or XIncludes).
Note that libxml2 has a global pool of loaded catalogs, so if you apply the
method C<<<<<< load_catalog >>>>>> to one parser instance, all parser instances will start using the catalog (in
addition to other previously loaded catalogs).
Note also that catalogs are not used when a custom external entity handler is
specified. At the current state it is not possible to make use of both types of
resolving systems at the same time.
=over 4
=item load_catalog
$parser->load_catalog( $catalog_file );
Loads the XML catalog file $catalog_file.
# Global external entity loader (similar to ext_ent_handler option
# but this works really globally, also in XML::LibXSLT include etc..)
XML::LibXML::externalEntityLoader(\&my_loader);
=back
=head1 ERROR REPORTING
XML::LibXML throws exceptions during parsing, validation or XPath processing
(and some other occasions). These errors can be caught by using I<<<<<< eval >>>>>> blocks. The error is stored in I<<<<<< $@ >>>>>>. There are two implementations: the old one throws $@ which is just a message
string, in the new one $@ is an object from the class XML::LibXML::Error; this
class overrides the operator "" so that when printed, the object flattens to
the usual error message.
XML::LibXML throws errors as they occur. This is a very common misunderstanding
in the use of XML::LibXML. If the eval is omitted, XML::LibXML will always halt
your script by "croaking" (see Carp man page for details).
Also note that an increasing number of functions throw errors if bad data is
passed as arguments. If you cannot assure valid data passed to XML::LibXML you
should eval these functions.
Note: since version 1.59, get_last_error() is no longer available in
XML::LibXML for thread-safety reasons.
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\i^ ^ LibXML/RelaxNG.podnu 6$ =head1 NAME
XML::LibXML::RelaxNG - RelaxNG Schema Validation
=head1 SYNOPSIS
use XML::LibXML;
$doc = XML::LibXML->new->parse_file($url);
$rngschema = XML::LibXML::RelaxNG->new( location => $filename_or_url, no_network => 1 );
$rngschema = XML::LibXML::RelaxNG->new( string => $xmlschemastring, no_network => 1 );
$rngschema = XML::LibXML::RelaxNG->new( DOM => $doc, no_network => 1 );
eval { $rngschema->validate( $doc ); };
=head1 DESCRIPTION
The XML::LibXML::RelaxNG class is a tiny frontend to libxml2's RelaxNG
implementation. Currently it supports only schema parsing and document
validation.
=head1 METHODS
=over 4
=item new
$rngschema = XML::LibXML::RelaxNG->new( location => $filename_or_url, no_network => 1 );
$rngschema = XML::LibXML::RelaxNG->new( string => $xmlschemastring, no_network => 1 );
$rngschema = XML::LibXML::RelaxNG->new( DOM => $doc, no_network => 1 );
The constructor of XML::LibXML::RelaxNG needs to be called with list of
parameters. At least location, string or DOM parameter is required to specify
source of schema. Optional parameter no_network set to 1 cause that parser
would not access network and optional parameter recover set 1 cause that parser
would not call die() on errors.
It is important, that each schema only have a single source.
The location parameter allows one to parse a schema from the filesystem or a
(non-HTTPS) URL.
The string parameter will parse the schema from the given XML string.
The DOM parameter allows one to parse the schema from a pre-parsed L<<<<<< XML::LibXML::Document >>>>>>.
Note that the constructor will die() if the schema does not meed the
constraints of the RelaxNG specification.
=item validate
eval { $rngschema->validate( $doc ); };
This function allows one to validate a (parsed) document against the given
RelaxNG schema. The argument of this function should be an
XML::LibXML::Document object. If this function succeeds, it will return 0,
otherwise it will die() and report the errors found. Because of this validate()
should be always evaluated.
=back
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\,W- - LibXML/XPathContext.podnu 6$ =head1 NAME
XML::LibXML::XPathContext - XPath Evaluation
=head1 SYNOPSIS
my $xpc = XML::LibXML::XPathContext->new();
my $xpc = XML::LibXML::XPathContext->new($node);
$xpc->registerNs($prefix, $namespace_uri)
$xpc->unregisterNs($prefix)
$uri = $xpc->lookupNs($prefix)
$xpc->registerVarLookupFunc($callback, $data)
$data = $xpc->getVarLookupData();
$callback = $xpc->getVarLookupFunc();
$xpc->unregisterVarLookupFunc($name);
$xpc->registerFunctionNS($name, $uri, $callback)
$xpc->unregisterFunctionNS($name, $uri)
$xpc->registerFunction($name, $callback)
$xpc->unregisterFunction($name)
@nodes = $xpc->findnodes($xpath)
@nodes = $xpc->findnodes($xpath, $context_node )
$nodelist = $xpc->findnodes($xpath, $context_node )
$object = $xpc->find($xpath )
$object = $xpc->find($xpath, $context_node )
$value = $xpc->findvalue($xpath )
$value = $xpc->findvalue($xpath, $context_node )
$bool = $xpc->exists( $xpath_expression, $context_node );
$xpc->setContextNode($node)
my $node = $xpc->getContextNode;
$xpc->setContextPosition($position)
my $position = $xpc->getContextPosition;
$xpc->setContextSize($size)
my $size = $xpc->getContextSize;
$xpc->setContextNode($node)
=head1 DESCRIPTION
The XML::LibXML::XPathContext class provides an almost complete interface to
libxml2's XPath implementation. With XML::LibXML::XPathContext, it is possible
to evaluate XPath expressions in the context of arbitrary node, context size,
and context position, with a user-defined namespace-prefix mapping, custom
XPath functions written in Perl, and even a custom XPath variable resolver.
=head1 EXAMPLES
=head2 Namespaces
This example demonstrates C<<<<<< registerNs() >>>>>> method. It finds all paragraph nodes in an XHTML document.
my $xc = XML::LibXML::XPathContext->new($xhtml_doc);
$xc->registerNs('xhtml', 'http://www.w3.org/1999/xhtml');
my @nodes = $xc->findnodes('//xhtml:p');
=head2 Custom XPath functions
This example demonstrates C<<<<<< registerFunction() >>>>>> method by defining a function filtering nodes based on a Perl regular
expression:
sub grep_nodes {
my ($nodelist,$regexp) = @_;
my $result = XML::LibXML::NodeList->new;
for my $node ($nodelist->get_nodelist()) {
$result->push($node) if $node->textContent =~ $regexp;
}
return $result;
};
my $xc = XML::LibXML::XPathContext->new($node);
$xc->registerFunction('grep_nodes', \&grep_nodes);
my @nodes = $xc->findnodes('//section[grep_nodes(para,"\bsearch(ing|es)?\b")]');
=head2 Variables
This example demonstrates C<<<<<< registerVarLookup() >>>>>> method. We use XPath variables to recycle results of previous evaluations:
sub var_lookup {
my ($varname,$ns,$data)=@_;
return $data->{$varname};
}
my $areas = XML::LibXML->new->parse_file('areas.xml');
my $empl = XML::LibXML->new->parse_file('employees.xml');
my $xc = XML::LibXML::XPathContext->new($empl);
my %variables = (
A => $xc->find('/employees/employee[@salary>10000]'),
B => $areas->find('/areas/area[district='Brooklyn']/street'),
);
# get names of employees from $A working in an area listed in $B
$xc->registerVarLookupFunc(\&var_lookup, \%variables);
my @nodes = $xc->findnodes('$A[work_area/street = $B]/name');
=head1 METHODS
=over 4
=item new
my $xpc = XML::LibXML::XPathContext->new();
Creates a new XML::LibXML::XPathContext object without a context node.
my $xpc = XML::LibXML::XPathContext->new($node);
Creates a new XML::LibXML::XPathContext object with the context node set to C<<<<<< $node >>>>>>.
=item registerNs
$xpc->registerNs($prefix, $namespace_uri)
Registers namespace C<<<<<< $prefix >>>>>> to C<<<<<< $namespace_uri >>>>>>.
=item unregisterNs
$xpc->unregisterNs($prefix)
Unregisters namespace C<<<<<< $prefix >>>>>>.
=item lookupNs
$uri = $xpc->lookupNs($prefix)
Returns namespace URI registered with C<<<<<< $prefix >>>>>>. If C<<<<<< $prefix >>>>>> is not registered to any namespace URI returns C<<<<<< undef >>>>>>.
=item registerVarLookupFunc
$xpc->registerVarLookupFunc($callback, $data)
Registers variable lookup function C<<<<<< $callback >>>>>>. The registered function is executed by the XPath engine each time an XPath
variable is evaluated. It takes three arguments: C<<<<<< $data >>>>>>, variable name, and variable ns-URI and must return one value: a number or
string or any C<<<<<< XML::LibXML:: >>>>>> object that can be a result of findnodes: Boolean, Literal, Number, Node (e.g.
Document, Element, etc.), or NodeList. For convenience, simple (non-blessed)
array references containing only L<<<<<< XML::LibXML::Node >>>>>> objects can be used instead of an L<<<<<< XML::LibXML::NodeList >>>>>>.
=item getVarLookupData
$data = $xpc->getVarLookupData();
Returns the data that have been associated with a variable lookup function
during a previous call to C<<<<<< registerVarLookupFunc >>>>>>.
=item getVarLookupFunc
$callback = $xpc->getVarLookupFunc();
Returns the variable lookup function previously registered with C<<<<<< registerVarLookupFunc >>>>>>.
=item unregisterVarLookupFunc
$xpc->unregisterVarLookupFunc($name);
Unregisters variable lookup function and the associated lookup data.
=item registerFunctionNS
$xpc->registerFunctionNS($name, $uri, $callback)
Registers an extension function C<<<<<< $name >>>>>> in C<<<<<< $uri >>>>>> namespace. C<<<<<< $callback >>>>>> must be a CODE reference. The arguments of the callback function are either
simple scalars or C<<<<<< XML::LibXML::* >>>>>> objects depending on the XPath argument types. The function is responsible for
checking the argument number and types. Result of the callback code must be a
single value of the following types: a simple scalar (number, string) or an
arbitrary C<<<<<< XML::LibXML::* >>>>>> object that can be a result of findnodes: Boolean, Literal, Number, Node (e.g.
Document, Element, etc.), or NodeList. For convenience, simple (non-blessed)
array references containing only L<<<<<< XML::LibXML::Node >>>>>> objects can be used instead of a L<<<<<< XML::LibXML::NodeList >>>>>>.
=item unregisterFunctionNS
$xpc->unregisterFunctionNS($name, $uri)
Unregisters extension function C<<<<<< $name >>>>>> in C<<<<<< $uri >>>>>> namespace. Has the same effect as passing C<<<<<< undef >>>>>> as C<<<<<< $callback >>>>>> to registerFunctionNS.
=item registerFunction
$xpc->registerFunction($name, $callback)
Same as C<<<<<< registerFunctionNS >>>>>> but without a namespace.
=item unregisterFunction
$xpc->unregisterFunction($name)
Same as C<<<<<< unregisterFunctionNS >>>>>> but without a namespace.
=item findnodes
@nodes = $xpc->findnodes($xpath)
@nodes = $xpc->findnodes($xpath, $context_node )
$nodelist = $xpc->findnodes($xpath, $context_node )
Performs the xpath statement on the current node and returns the result as an
array. In scalar context, returns an L<<<<<< XML::LibXML::NodeList >>>>>> object. Optionally, a node may be passed as a second argument to set the
context node for the query.
The xpath expression can be passed either as a string, or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
=item find
$object = $xpc->find($xpath )
$object = $xpc->find($xpath, $context_node )
Performs the xpath expression using the current node as the context of the
expression, and returns the result depending on what type of result the XPath
expression had. For example, the XPath C<<<<<< 1 * 3 + 52 >>>>>> results in an L<<<<<< XML::LibXML::Number >>>>>> object being returned. Other expressions might return a L<<<<<< XML::LibXML::Boolean >>>>>> object, or a L<<<<<< XML::LibXML::Literal >>>>>> object (a string). Each of those objects uses Perl's overload feature to ``do
the right thing'' in different contexts. Optionally, a node may be passed as a
second argument to set the context node for the query.
The xpath expression can be passed either as a string, or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
=item findvalue
$value = $xpc->findvalue($xpath )
$value = $xpc->findvalue($xpath, $context_node )
Is exactly equivalent to:
$xpc->find( $xpath, $context_node )->to_literal;
That is, it returns the literal value of the results. This enables you to
ensure that you get a string back from your search, allowing certain shortcuts.
This could be used as the equivalent of .
Optionally, a node may be passed in the second argument to set the context node
for the query.
The xpath expression can be passed either as a string, or as a L<<<<<< XML::LibXML::XPathExpression >>>>>> object.
=item exists
$bool = $xpc->exists( $xpath_expression, $context_node );
This method behaves like I<<<<<< findnodes >>>>>>, except that it only returns a boolean value (1 if the expression matches a
node, 0 otherwise) and may be faster than I<<<<<< findnodes >>>>>>, because the XPath evaluation may stop early on the first match (this is true
for libxml2 >= 2.6.27).
For XPath expressions that do not return node-set, the method returns true if
the returned value is a non-zero number or a non-empty string.
=item setContextNode
$xpc->setContextNode($node)
Set the current context node.
=item getContextNode
my $node = $xpc->getContextNode;
Get the current context node.
=item setContextPosition
$xpc->setContextPosition($position)
Set the current context position. By default, this value is -1 (and evaluating
XPath function C<<<<<< position() >>>>>> in the initial context raises an XPath error), but can be set to any value up
to context size. This usually only serves to cheat the XPath engine to return
given position when C<<<<<< position() >>>>>> XPath function is called. Setting this value to -1 restores the default
behavior.
=item getContextPosition
my $position = $xpc->getContextPosition;
Get the current context position.
=item setContextSize
$xpc->setContextSize($size)
Set the current context size. By default, this value is -1 (and evaluating
XPath function C<<<<<< last() >>>>>> in the initial context raises an XPath error), but can be set to any
non-negative value. This usually only serves to cheat the XPath engine to
return the given value when C<<<<<< last() >>>>>> XPath function is called. If context size is set to 0, position is
automatically also set to 0. If context size is positive, position is
automatically set to 1. Setting context size to -1 restores the default
behavior.
=item getContextSize
my $size = $xpc->getContextSize;
Get the current context size.
=item setContextNode
$xpc->setContextNode($node)
Set the current context node.
=back
=head1 BUGS AND CAVEATS
XML::LibXML::XPathContext objects I<<<<<< are >>>>>> reentrant, meaning that you can call methods of an XML::LibXML::XPathContext
even from XPath extension functions registered with the same object or from a
variable lookup function. On the other hand, you should rather avoid
registering new extension functions, namespaces and a variable lookup function
from within extension functions and a variable lookup function, unless you want
to experience untested behavior.
=head1 AUTHORS
Ilya Martynov and Petr Pajas, based on XML::LibXML and XML::LibXSLT code by
Matt Sergeant and Christian Glahn.
=head1 HISTORICAL REMARK
Prior to XML::LibXML 1.61 this module was distributed separately for
maintenance reasons.
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\t9UX X LibXML/Common.podnu 6$ =head1 NAME
XML::LibXML::Common - Constants and Character Encoding Routines
=head1 SYNOPSIS
use XML::LibXML::Common;
$encodedstring = encodeToUTF8( $name_of_encoding, $sting_to_encode );
$decodedstring = decodeFromUTF8($name_of_encoding, $string_to_decode );
=head1 DESCRIPTION
XML::LibXML::Common defines constants for all node types and provides interface
to libxml2 charset conversion functions.
Since XML::LibXML use their own node type definitions, one may want to use
XML::LibXML::Common in its compatibility mode:
=head2 Exporter TAGS
use XML::LibXML::Common qw(:libxml);
C<<<<<< :libxml >>>>>> tag will use the XML::LibXML Compatibility mode, which defines the old 'XML_'
node-type definitions.
use XML::LibXML::Common qw(:gdome);
C<<<<<< :gdome >>>>>> tag will use the XML::GDOME Compatibility mode, which defines the old 'GDOME_'
node-type definitions.
use XML::LibXML::Common qw(:w3c);
This uses the nodetype definition names as specified for DOM.
use XML::LibXML::Common qw(:encoding);
This tag can be used to export only the charset encoding functions of
XML::LibXML::Common.
=head2 Exports
By default the W3 definitions as defined in the DOM specifications and the
encoding functions are exported by XML::LibXML::Common.
=head2 Encoding functions
To encode or decode a string to or from UTF-8, XML::LibXML::Common exports two
functions, which provide an interface to the encoding support in C<<<<<< libxml2 >>>>>>. Which encodings are supported by these functions depends on how C<<<<<< libxml2 >>>>>> was compiled. UTF-16 is always supported and on most installations, ISO
encodings are supported as well.
This interface was useful for older versions of Perl. Since Perl >= 5.8
provides similar functions via the C<<<<<< Encode >>>>>> module, it is probably a good idea to use those instead.
=over 4
=item encodeToUTF8
$encodedstring = encodeToUTF8( $name_of_encoding, $sting_to_encode );
The function will convert a byte string from the specified encoding to an UTF-8
encoded character string.
=item decodeToUTF8
$decodedstring = decodeFromUTF8($name_of_encoding, $string_to_decode );
This function converts an UTF-8 encoded character string to a specified
encoding. Note that the conversion can raise an error if the given string
contains characters that cannot be represented in the target encoding.
=back
Both these functions report their errors on the standard error. If an error
occurs the function will croak(). To catch the error information it is required
to call the encoding function from within an eval block in order to prevent the
entire script from being stopped on encoding error.
=head2 A note on history
Before XML::LibXML 1.70, this class was available as a separate CPAN
distribution, intended to provide functionality shared between XML::LibXML,
XML::GDOME, and possibly other modules. Since there seems to be no progress in
this direction, we decided to merge XML::LibXML::Common 0.13 and XML::LibXML
1.70 to one CPAN distribution.
The merge also naturally eliminates a practical and urgent problem experienced
by many XML::LibXML users on certain platforms, namely mysterious misbehavior
of XML::LibXML occurring if the installed (often pre-packaged) version of
XML::LibXML::Common was compiled against an older version of libxml2 than
XML::LibXML.
=head1 AUTHORS
Matt Sergeant,
Christian Glahn,
Petr Pajas
=head1 VERSION
2.0210
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
=head1 LICENSE
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
PK N\A A LibXML/NodeList.pmnu 6$ # $Id$
#
# This is free software, you may use it and distribute it under the same terms as
# Perl itself.
#
# Copyright 2001-2003 AxKit.com Ltd., 2002-2006 Christian Glahn, 2006-2009 Petr Pajas
#
#
package XML::LibXML::NodeList;
use strict;
use warnings;
use XML::LibXML::Boolean;
use XML::LibXML::Literal;
use XML::LibXML::Number;
use vars qw($VERSION);
$VERSION = "2.0210"; # VERSION TEMPLATE: DO NOT CHANGE
use overload
'""' => \&to_literal,
'bool' => \&to_boolean,
'cmp' => sub {
my($aa, $bb, $order) = @_;
return ($order ? ("$bb" cmp "$aa") : ("$aa" cmp "$bb"));
},
;
sub new {
my $class = shift;
bless [@_], $class;
}
sub new_from_ref {
my ($class,$array_ref,$reuse) = @_;
return bless $reuse ? $array_ref : [@$array_ref], $class;
}
sub pop {
my $self = CORE::shift;
CORE::pop @$self;
}
sub push {
my $self = CORE::shift;
CORE::push @$self, @_;
}
sub append {
my $self = CORE::shift;
my ($nodelist) = @_;
CORE::push @$self, $nodelist->get_nodelist;
}
sub shift {
my $self = CORE::shift;
CORE::shift @$self;
}
sub unshift {
my $self = CORE::shift;
CORE::unshift @$self, @_;
}
sub prepend {
my $self = CORE::shift;
my ($nodelist) = @_;
CORE::unshift @$self, $nodelist->get_nodelist;
}
sub size {
my $self = CORE::shift;
scalar @$self;
}
sub get_node {
# uses array index starting at 1, not 0
# this is mainly because of XPath.
my $self = CORE::shift;
my ($pos) = @_;
$self->[$pos - 1];
}
sub item
{
my ($self, $pos) = @_;
return $self->[$pos];
}
sub get_nodelist {
my $self = CORE::shift;
@$self;
}
sub to_boolean {
my $self = CORE::shift;
return (@$self > 0) ? XML::LibXML::Boolean->True : XML::LibXML::Boolean->False;
}
# string-value of a nodelist is the string-value of the first node
sub string_value {
my $self = CORE::shift;
return '' unless @$self;
return $self->[0]->string_value;
}
sub to_literal {
my $self = CORE::shift;
return XML::LibXML::Literal->new(
join('', CORE::grep {defined $_} CORE::map { $_->string_value } @$self)
);
}
sub to_literal_delimited {
my $self = CORE::shift;
return XML::LibXML::Literal->new(
join(CORE::shift, CORE::grep {defined $_} CORE::map { $_->string_value } @$self)
);
}
sub to_literal_list {
my $self = CORE::shift;
my @nodes = CORE::map{ XML::LibXML::Literal->new($_->string_value())->value() } @{$self};
if (wantarray) {
return( @nodes );
}
return( \@nodes );
}
sub to_number {
my $self = CORE::shift;
return XML::LibXML::Number->new(
$self->to_literal
);
}
sub iterator {
warn "this function is obsolete!\nIt was disabled in version 1.54\n";
return undef;
}
sub map {
my $self = CORE::shift;
my $sub = __is_code(CORE::shift);
local $_;
my @results = CORE::map { @{[ $sub->($_) ]} } @$self;
return unless defined wantarray;
return wantarray ? @results : (ref $self)->new(@results);
}
sub grep {
my $self = CORE::shift;
my $sub = __is_code(CORE::shift);
local $_;
my @results = CORE::grep { $sub->($_) } @$self;
return unless defined wantarray;
return wantarray ? @results : (ref $self)->new(@results);
}
sub sort {
my $self = CORE::shift;
my $sub = __is_code(CORE::shift);
my @results = CORE::sort { $sub->($a,$b) } @$self;
return wantarray ? @results : (ref $self)->new(@results);
}
sub foreach {
my $self = CORE::shift;
my $sub = CORE::shift;
foreach my $item (@$self)
{
local $_ = $item;
$sub->($item);
}
return wantarray ? @$self : $self;
}
sub reverse {
my $self = CORE::shift;
my @results = CORE::reverse @$self;
return wantarray ? @results : (ref $self)->new(@results);
}
sub reduce {
my $self = CORE::shift;
my $sub = __is_code(CORE::shift);
my @list = @$self;
CORE::unshift @list, $_[0] if @_;
my $a = CORE::shift(@list);
foreach my $b (@list)
{
$a = $sub->($a, $b);
}
return $a;
}
sub __is_code {
my ($code) = @_;
if (ref $code eq 'CODE') {
return $code;
}
# There are better ways of doing this, but here I've tried to
# avoid adding any additional external dependencies.
#
if (UNIVERSAL::can($code, 'can') # is blessed (sort of)
and overload::Overloaded($code) # is overloaded
and overload::Method($code, '&{}')) { # overloads '&{}'
return $code;
}
# The other possibility is that $code is a coderef, but is
# blessed into a class that doesn't overload '&{}'. In which
# case... well, I'm stumped!
die "Not a subroutine reference\n";
}
1;
__END__
=head1 NAME
XML::LibXML::NodeList - a list of XML document nodes
=head1 DESCRIPTION
An XML::LibXML::NodeList object contains an ordered list of nodes, as
detailed by the W3C DOM documentation of Node Lists.
=head1 SYNOPSIS
my $results = $dom->findnodes('//somepath');
foreach my $context ($results->get_nodelist) {
my $newresults = $context->findnodes('./other/element');
...
}
=head1 API
=head2 new(@nodes)
You will almost never have to create a new NodeList object, as it is all
done for you by XPath.
=head2 get_nodelist()
Returns a list of nodes, the contents of the node list, as a perl list.
=head2 string_value()
Returns the string-value of the first node in the list.
See the XPath specification for what "string-value" means.
=head2 to_literal()
Returns the concatenation of all the string-values of all
the nodes in the list.
=head2 to_literal_delimited($separator)
Returns the concatenation of all the string-values of all
the nodes in the list, delimited by the specified separator.
=head2 to_literal_list()
Returns all the string-values of all the nodes in the list as
a perl list.
=head2 get_node($pos)
Returns the node at $pos. The node position in XPath is based at 1, not 0.
=head2 size()
Returns the number of nodes in the NodeList.
=head2 pop()
Equivalent to perl's pop function.
=head2 push(@nodes)
Equivalent to perl's push function.
=head2 append($nodelist)
Given a nodelist, appends the list of nodes in $nodelist to the end of the
current list.
=head2 shift()
Equivalent to perl's shift function.
=head2 unshift(@nodes)
Equivalent to perl's unshift function.
=head2 prepend($nodelist)
Given a nodelist, prepends the list of nodes in $nodelist to the front of
the current list.
=head2 map($coderef)
Equivalent to perl's map function.
=head2 grep($coderef)
Equivalent to perl's grep function.
=head2 sort($coderef)
Equivalent to perl's sort function.
Caveat: Perl's magic C<$a> and C<$b> variables are not available in
C<$coderef>. Instead the two terms are passed to the coderef as arguments.
=head2 reverse()
Equivalent to perl's reverse function.
=head2 foreach($coderef)
Inspired by perl's foreach loop. Executes the coderef on each item in
the list. Similar to C