Difference between revisions of "API:EPrints/XML"

From EPrints Documentation
Jump to: navigation, search
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/XML.pm|package_name=EPrints::XML}}[[Category:API|XML]]<div><!-- Edit below this comment -->
__NOTOC__
+
{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/XML.pm|package_name=EPrints::XML}}[[Category:API|XML]]<div><!-- Edit below this comment -->
+
  
  
<!-- Pod2Wiki=head_name --></div>
+
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
 
'''EPrints::XML''' - XML Abstraction Module
 
'''EPrints::XML''' - XML Abstraction Module
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
 
  
  
 
For preference, use the methods in [[API:EPrints/Handle/XML|EPrints::Handle::XML]]
 
For preference, use the methods in [[API:EPrints/Handle/XML|EPrints::Handle::XML]]
  
<!-- Pod2Wiki=head_synopsis --></div>
+
 
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_synopsis -->
 
==SYNOPSIS==
 
==SYNOPSIS==
 
   my $xml = $repository-&gt;xml;
 
   my $xml = $repository-&gt;xml;
Line 48: Line 48:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_methods --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_methods -->
 
==METHODS==
 
==METHODS==
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_parsing --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_parsing -->
 
===Parsing===
 
===Parsing===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_parse_string --></div>
+
<!-- Pod2Wiki= -->
====$doc = $xml-&gt;parse_string( $string, %opts )====
+
</div>
 +
<!-- Pod2Wiki=item_parse_string -->
 +
====parse_string====
  
 +
$doc = $xml-&gt;parse_string( $string, %opts )
 
Returns an XML document parsed from $string.
 
Returns an XML document parsed from $string.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_parse_file --></div>
+
<!-- Pod2Wiki= -->
====$doc = $xml-&gt;parse_file( $filename, %opts )====
+
</div>
 +
<!-- Pod2Wiki=item_parse_file -->
 +
====parse_file====
  
 +
$doc = $xml-&gt;parse_file( $filename, %opts )
 
Returns an XML document parsed from the file called $filename.
 
Returns an XML document parsed from the file called $filename.
  
Line 85: Line 95:
 
    
 
    
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_parse_url --></div>
+
<!-- Pod2Wiki= -->
====$doc = $xml-&gt;parse_url( $url, %opts )====
+
</div>
 +
<!-- Pod2Wiki=item_parse_url -->
 +
====parse_url====
  
 +
$doc = $xml-&gt;parse_url( $url, %opts )
 
Returns an XML document parsed from the content located at $url.
 
Returns an XML document parsed from the content located at $url.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_node_creation --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_node_creation -->
 
===Node Creation===
 
===Node Creation===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_create_element --></div>
+
<!-- Pod2Wiki= -->
====$node = $xml-&gt;create_element( $name [, @attrs ] )====
+
</div>
 +
<!-- Pod2Wiki=item_create_element -->
 +
====create_element====
  
 +
$node = $xml-&gt;create_element( $name [, @attrs ] )
 
Returns a new XML element named $name with optional attribute pairs @attrs.
 
Returns a new XML element named $name with optional attribute pairs @attrs.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_create_cdata_section --></div>
+
<!-- Pod2Wiki= -->
====$node = $xml-&gt;create_cdata_section( $value )====
+
</div>
 +
<!-- Pod2Wiki=item_create_cdata_section -->
 +
====create_cdata_section====
  
 +
$node = $xml-&gt;create_cdata_section( $value )
 
Returns a CDATA section containing $value.
 
Returns a CDATA section containing $value.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_create_text_node --></div>
+
<!-- Pod2Wiki= -->
====$node = $xml-&gt;create_text_node( $value )====
+
</div>
 +
<!-- Pod2Wiki=item_create_text_node -->
 +
====create_text_node====
  
 +
$node = $xml-&gt;create_text_node( $value )
 
Returns a new XML text node containing $value.
 
Returns a new XML text node containing $value.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_create_comment --></div>
+
<!-- Pod2Wiki= -->
====$node = $xml-&gt;create_comment( $value )====
+
</div>
 +
<!-- Pod2Wiki=item_create_comment -->
 +
====create_comment====
  
 +
$node = $xml-&gt;create_comment( $value )
 
Returns a new XML comment containing $value.
 
Returns a new XML comment containing $value.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_create_document_fragment --></div>
+
<!-- Pod2Wiki= -->
====$node = $xml-&gt;create_document_fragment====
+
</div>
 +
<!-- Pod2Wiki=item_create_document_fragment -->
 +
====create_document_fragment====
  
 +
$node = $xml-&gt;create_document_fragment
 
Returns a new XML document fragment.
 
Returns a new XML document fragment.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_other --></div>
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_other -->
 
===Other===
 
===Other===
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_is --></div>
+
<!-- Pod2Wiki= -->
====$bool = $xml-&gt;is( $node, $type [, $type ... ] )====
+
</div>
 +
<!-- Pod2Wiki=item_is -->
 +
====is====
  
 +
$bool = $xml-&gt;is( $node, $type [, $type ... ] )
 
Returns true if $node is one of the given node types: Document, DocumentFragment, Element, Comment, Text.
 
Returns true if $node is one of the given node types: Document, DocumentFragment, Element, Comment, Text.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_clone --></div>
+
<!-- Pod2Wiki= -->
====$node = $xml-&gt;clone( $node )====
+
</div>
 +
<!-- Pod2Wiki=item_clone -->
 +
====clone====
  
 +
$node = $xml-&gt;clone( $node )
 
Returns a deep clone of $node. The new node(s) will be owned by this object.
 
Returns a deep clone of $node. The new node(s) will be owned by this object.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_clone_node --></div>
+
<!-- Pod2Wiki= -->
====$node = $xml-&gt;clone_node( $node )====
+
</div>
 +
<!-- Pod2Wiki=item_clone_node -->
 +
====clone_node====
  
 +
$node = $xml-&gt;clone_node( $node )
 
Returns a clone of $node only (no children). The new node will be owned by this object.
 
Returns a clone of $node only (no children). The new node will be owned by this object.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_clone_node --></div>
+
<!-- Pod2Wiki= -->
====$node = EPrints::XML::clone_node( $node [, $deep ] )====
+
</div>
 +
<!-- Pod2Wiki=item_clone_node -->
 +
====clone_node====
  
 +
$node = EPrints::XML::clone_node( $node [, $deep ] )
 
DEPRECATED.
 
DEPRECATED.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_contents_of --></div>
+
<!-- Pod2Wiki= -->
====$node = $xml-&gt;contents_of( $node )====
+
</div>
 +
<!-- Pod2Wiki=item_contents_of -->
 +
====contents_of====
  
 +
$node = $xml-&gt;contents_of( $node )
 
Returns a document fragment containing a copy of all the children of $node.
 
Returns a document fragment containing a copy of all the children of $node.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_text_contents_of --></div>
+
<!-- Pod2Wiki= -->
====$string = $xml-&gt;text_contents_of( $node )====
+
</div>
 +
<!-- Pod2Wiki=item_text_contents_of -->
 +
====text_contents_of====
  
 +
$string = $xml-&gt;text_contents_of( $node )
 
Returns the concantenated value of all text nodes in $node (or the value of $node if $node is a text node).
 
Returns the concantenated value of all text nodes in $node (or the value of $node if $node is a text node).
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_to_string --></div>
+
<!-- Pod2Wiki= -->
====$utf8_string = $xml-&gt;to_string( $node, %opts )====
+
</div>
 +
<!-- Pod2Wiki=item_to_string -->
 +
====to_string====
  
 +
$utf8_string = $xml-&gt;to_string( $node, %opts )
 
Serialises and returns the $node as a UTF-8 string.
 
Serialises and returns the $node as a UTF-8 string.
  
Line 234: Line 287:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_to_string --></div>
+
<!-- Pod2Wiki= -->
====$string = EPrints::XML::to_string( $node, [$enc], [$noxmlns] )====
+
</div>
 +
<!-- Pod2Wiki=item_to_string -->
 +
====to_string====
  
 +
$string = EPrints::XML::to_string( $node, [$enc], [$noxmlns] )
 
Return the given node (and its children) as a UTF8 encoded string.
 
Return the given node (and its children) as a UTF8 encoded string.
  
Line 250: Line 306:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_dispose --></div>
+
<!-- Pod2Wiki= -->
====$xml-&gt;dispose( $node )====
+
</div>
 +
<!-- Pod2Wiki=item_dispose -->
 +
====dispose====
  
 +
$xml-&gt;dispose( $node )
 
Dispose and free the memory used by $node.
 
Dispose and free the memory used by $node.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_parse_xml --></div>
+
<!-- Pod2Wiki= -->
====$doc = EPrints::XML::parse_xml( $file, $basepath, $no_expand )====
+
</div>
 +
<!-- Pod2Wiki=item_parse_xml -->
 +
====parse_xml====
  
 +
$doc = EPrints::XML::parse_xml( $file, $basepath, $no_expand )
 
Return a DOM document describing the XML file specified by $file. With the optional root path for looking for the DTD of $basepath. If $noexpand is true then entities will not be expanded.
 
Return a DOM document describing the XML file specified by $file. With the optional root path for looking for the DTD of $basepath. If $noexpand is true then entities will not be expanded.
  
Line 274: Line 336:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_event_parse --></div>
+
<!-- Pod2Wiki= -->
====event_parse( $fh, $handler )====
+
</div>
 +
<!-- Pod2Wiki=item_event_parse -->
 +
====event_parse====
  
 +
event_parse( $fh, $handler )
 
Parses the XML from filehandle $fh, calling the appropriate events in the handler where necessary.
 
Parses the XML from filehandle $fh, calling the appropriate events in the handler where necessary.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_is_dom --></div>
+
<!-- Pod2Wiki= -->
====$boolean = is_dom( $node, @nodestrings )====
+
</div>
 +
<!-- Pod2Wiki=item_is_dom -->
 +
====is_dom====
  
 +
$boolean = is_dom( $node, @nodestrings )
 
  return true if node is an object of type XML::DOM/GDOME::$nodestring
 
  return true if node is an object of type XML::DOM/GDOME::$nodestring
 
  where $nodestring is any value in @nodestrings.
 
  where $nodestring is any value in @nodestrings.
Line 298: Line 366:
 
    
 
    
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_clone_and_own --></div>
+
<!-- Pod2Wiki= -->
====$newnode = EPrints::XML::clone_and_own( $doc, $node, $deep )====
+
</div>
 +
<!-- Pod2Wiki=item_clone_and_own -->
 +
====clone_and_own====
  
 +
$newnode = EPrints::XML::clone_and_own( $doc, $node, $deep )
 
This function abstracts the different ways that XML::DOM and  XML::GDOME allow objects to be moved between documents.  
 
This function abstracts the different ways that XML::DOM and  XML::GDOME allow objects to be moved between documents.  
  
Line 312: Line 383:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_make_document --></div>
+
<!-- Pod2Wiki= -->
====$document = EPrints::XML::make_document()====
+
</div>
 +
<!-- Pod2Wiki=item_make_document -->
 +
====make_document====
  
 +
$document = EPrints::XML::make_document()
 
Create and return an empty document.
 
Create and return an empty document.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_write_xml_file --></div>
+
<!-- Pod2Wiki= -->
====EPrints::XML::write_xml_file( $node, $filename )====
+
</div>
 +
<!-- Pod2Wiki=item_write_xml_file -->
 +
====write_xml_file====
  
 +
EPrints::XML::write_xml_file( $node, $filename )
 
Write the given XML node $node to file $filename.
 
Write the given XML node $node to file $filename.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_write_xhtml_file --></div>
+
<!-- Pod2Wiki= -->
====EPrints::XML::write_xhtml_file( $node, $filename )====
+
</div>
 +
<!-- Pod2Wiki=item_write_xhtml_file -->
 +
====write_xhtml_file====
  
 +
EPrints::XML::write_xhtml_file( $node, $filename )
 
Write the given XML node $node to file $filename with an XHTML doctype.
 
Write the given XML node $node to file $filename with an XHTML doctype.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_tidy --></div>
+
<!-- Pod2Wiki= -->
====EPrints::XML::tidy( $domtree, { collapse=&gt;['element','element'...] }, [$indent] )====
+
</div>
 +
<!-- Pod2Wiki=item_tidy -->
 +
====tidy====
  
 +
EPrints::XML::tidy( $domtree, { collapse=&gt;['element','element'...] }, [$indent] )
 
Neatly indent the DOM tree.  
 
Neatly indent the DOM tree.  
  
Line 358: Line 441:
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_namespace --></div>
+
<!-- Pod2Wiki= -->
====$namespace = EPrints::XML::namespace( $thing, $version )====
+
</div>
 +
<!-- Pod2Wiki=item_namespace -->
 +
====namespace====
  
 +
$namespace = EPrints::XML::namespace( $thing, $version )
 
Return the namespace for the given version of the eprints xml.
 
Return the namespace for the given version of the eprints xml.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_version --></div>
+
<!-- Pod2Wiki= -->
====$v = EPrints::XML::version()====
+
</div>
 +
<!-- Pod2Wiki=item_version -->
 +
====version====
  
 +
$v = EPrints::XML::version()
 
Returns a string description of the current XML library and version.
 
Returns a string description of the current XML library and version.
  
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
<h4><span style='display:none'>User Comments</span></h4>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->

Revision as of 13:21, 25 February 2010

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.3, 3.2) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::XML - XML Abstraction Module

User Comments


For preference, use the methods in EPrints::Handle::XML


SYNOPSIS

 my $xml = $repository->xml;
 
 $doc = $xml->parse_string( $string );
 $doc = $xml->parse_file( $filename );
 $doc = $xml->parse_url( $url );
 
 $utf8_string = $xml->to_string( $dom_node, %opts );
 
 $dom_node = $xml->clone( $dom_node ); # deep
 $dom_node = $xml->clone_node( $dom_node ); # shallow
 
 # clone and return child nodes
 $dom_node = $xml->contents_of( $dom_node );
 # Return text child nodes as a string
 $utf8_string = $xml->text_contents_of( $dom_node );
 
 $dom_node = $xml->create_element( $name, %attr );
 $dom_node = $xml->create_text_node( $value );
 $dom_node = $xml->create_comment( $value );
 $dom_node = $xml->create_document_fragment;
 
 $xml->dispose( $dom_node );
 

head1 DESCRIPTION

EPrints can use either XML::DOM, XML::LibXML or XML::GDOME modules to generate and process XML. Some of the functionality of these modules differs so this module abstracts such functionality so that all the module specific code is in one place.

User Comments


METHODS

User Comments


Parsing

User Comments


parse_string

$doc = $xml->parse_string( $string, %opts )

Returns an XML document parsed from $string.

User Comments


parse_file

$doc = $xml->parse_file( $filename, %opts )

Returns an XML document parsed from the file called $filename.

 base_path - base path to load DTD files from
 no_expand - don't expand entities
 

User Comments


parse_url

$doc = $xml->parse_url( $url, %opts )

Returns an XML document parsed from the content located at $url.

User Comments


Node Creation

User Comments


create_element

$node = $xml->create_element( $name [, @attrs ] )

Returns a new XML element named $name with optional attribute pairs @attrs.

User Comments


create_cdata_section

$node = $xml->create_cdata_section( $value )

Returns a CDATA section containing $value.

User Comments


create_text_node

$node = $xml->create_text_node( $value )

Returns a new XML text node containing $value.

User Comments


create_comment

$node = $xml->create_comment( $value )

Returns a new XML comment containing $value.

User Comments


create_document_fragment

$node = $xml->create_document_fragment

Returns a new XML document fragment.

User Comments


Other

User Comments


is

$bool = $xml->is( $node, $type [, $type ... ] )

Returns true if $node is one of the given node types: Document, DocumentFragment, Element, Comment, Text.

User Comments


clone

$node = $xml->clone( $node )

Returns a deep clone of $node. The new node(s) will be owned by this object.

User Comments


clone_node

$node = $xml->clone_node( $node )

Returns a clone of $node only (no children). The new node will be owned by this object.

User Comments


clone_node

$node = EPrints::XML::clone_node( $node [, $deep ] )

DEPRECATED.

User Comments


contents_of

$node = $xml->contents_of( $node )

Returns a document fragment containing a copy of all the children of $node.

User Comments


text_contents_of

$string = $xml->text_contents_of( $node )

Returns the concantenated value of all text nodes in $node (or the value of $node if $node is a text node).

User Comments


to_string

$utf8_string = $xml->to_string( $node, %opts )

Serialises and returns the $node as a UTF-8 string.

To generate an XHTML string see EPrints::XHTML.

Options: indent - if true will indent the XML tree

User Comments


to_string

$string = EPrints::XML::to_string( $node, [$enc], [$noxmlns] )

Return the given node (and its children) as a UTF8 encoded string.

$enc is only used when $node is a document.

If $stripxmlns is true then all xmlns attributes and namespace prefixes are removed. Handy for making legal XHTML.

Papers over some cracks, specifically that XML::GDOME does not support toString on a DocumentFragment, and that XML::GDOME does not insert a space before the / in tags with no children, which confuses some browsers. Eg. <br/> vs <br />

User Comments


dispose

$xml->dispose( $node )

Dispose and free the memory used by $node.

User Comments


parse_xml

$doc = EPrints::XML::parse_xml( $file, $basepath, $no_expand )

Return a DOM document describing the XML file specified by $file. With the optional root path for looking for the DTD of $basepath. If $noexpand is true then entities will not be expanded.

If we are using GDOME then it will create an XML::GDOME document instead.

In the event of an error in the XML file, report to STDERR and return undef.

User Comments


event_parse

event_parse( $fh, $handler )

Parses the XML from filehandle $fh, calling the appropriate events in the handler where necessary.

User Comments


is_dom

$boolean = is_dom( $node, @nodestrings )
return true if node is an object of type XML::DOM/GDOME::$nodestring
where $nodestring is any value in @nodestrings.
 
if $nodestring is not defined then return true if $node is any 
XML::DOM/GDOME object.
 

User Comments


clone_and_own

$newnode = EPrints::XML::clone_and_own( $doc, $node, $deep )

This function abstracts the different ways that XML::DOM and XML::GDOME allow objects to be moved between documents.

It returns a clone of $node but belonging to the document $doc no matter what document $node belongs to.

If $deep is true then the clone will also clone all nodes belonging to $node, recursively.

User Comments


make_document

$document = EPrints::XML::make_document()

Create and return an empty document.

User Comments


write_xml_file

EPrints::XML::write_xml_file( $node, $filename )

Write the given XML node $node to file $filename.

User Comments


write_xhtml_file

EPrints::XML::write_xhtml_file( $node, $filename )

Write the given XML node $node to file $filename with an XHTML doctype.

User Comments


tidy

EPrints::XML::tidy( $domtree, { collapse=>['element','element'...] }, [$indent] )

Neatly indent the DOM tree.

Note that this should not be done to XHTML as the differenct between white space and no white space does matter sometimes.

This method modifies the tree it is given. Possibly there should be a version which returns a new version without modifying the tree.

Indent is the number of levels to ident by.

User Comments


namespace

$namespace = EPrints::XML::namespace( $thing, $version )

Return the namespace for the given version of the eprints xml.

User Comments


version

$v = EPrints::XML::version()

Returns a string description of the current XML library and version.

User Comments