Difference between revisions of "API:EPrints/XML"

From EPrints Documentation
Jump to: navigation, search
Line 10: Line 10:
 
'''EPrints::XML''' - XML Abstraction Module
 
'''EPrints::XML''' - XML Abstraction Module
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 38: Line 38:
  
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 47: Line 47:
 
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.  
 
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.  
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 61: Line 61:
 
In the event of an error in the XML file, report to STDERR and return undef.
 
In the event of an error in the XML file, report to STDERR and return undef.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 75: Line 75:
 
In the event of an error in the XML file, report to STDERR and return undef.
 
In the event of an error in the XML file, report to STDERR and return undef.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 85: Line 85:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 99: Line 99:
 
  XML::DOM/GDOME object.
 
  XML::DOM/GDOME object.
 
    
 
    
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 109: Line 109:
 
Dispose of this node if needed. Only XML::DOM nodes need to be disposed as they have cyclic references. XML::GDOME nodes are C structs.
 
Dispose of this node if needed. Only XML::DOM nodes need to be disposed as they have cyclic references. XML::GDOME nodes are C structs.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 121: Line 121:
 
This function does different things for XML::DOM &amp; XML::GDOME but the result should be the same.
 
This function does different things for XML::DOM &amp; XML::GDOME but the result should be the same.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 135: Line 135:
 
If $deep is true then the clone will also clone all nodes belonging to $node, recursively.
 
If $deep is true then the clone will also clone all nodes belonging to $node, recursively.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 151: Line 151:
 
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. &lt;br/&gt; vs &lt;br /&gt;
 
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. &lt;br/&gt; vs &lt;br /&gt;
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 161: Line 161:
 
Create and return an empty document.
 
Create and return an empty document.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 171: Line 171:
 
Write the given XML node $node to file $filename.
 
Write the given XML node $node to file $filename.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 181: Line 181:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 197: Line 197:
 
Indent is the number of levels to ident by.
 
Indent is the number of levels to ident by.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 207: Line 207:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 217: Line 217:
 
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: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 231: Line 231:
 
$no_expand - set to 1 if you do not want the xml to be indented.
 
$no_expand - set to 1 if you do not want the xml to be indented.
  
<div style='background-color: #eef; 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>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->

Revision as of 14:04, 24 August 2009


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

 $string = EPrints::XML::to_string( $node, "utf-8", 1 ); #use this to convert DOM trees to string
 
 $dom = EPrints::XML::parse_xml_string( $string );
 
 $dom = EPrints::XML::parse_xml( $file, $basepath, $no_expand );
 
 $boolean = is_dom( $node, @nodestrings );
 
 $newnode = EPrints::XML::clone_node( $node, $deep );
 
 EPrints::XML::write_xhtml_file( $node, $filename );
 
 $document = EPrints::XML::make_document();
 
 $dom = EPrints:XML::parse_url($url, $no_expand);
 


User Comments


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


$doc = EPrints::XML::parse_xml_string( $string );

Return a DOM document describing the XML string %string.

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


$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( $fh, $handler )

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

User Comments


$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


EPrints::XML::dispose( $node )

Dispose of this node if needed. Only XML::DOM nodes need to be disposed as they have cyclic references. XML::GDOME nodes are C structs.

User Comments


$newnode = EPrints::XML::clone_node( $node, $deep )

Clone the given DOM node and return the new node. Always does a deep copy.

This function does different things for XML::DOM & XML::GDOME but the result should be the same.

User Comments


$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


$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


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

Create and return an empty document.

User Comments


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

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

User Comments


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

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

User Comments


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 = EPrints::XML::namespace( $thing, $version )

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

User Comments


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

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

User Comments


$dom = EPrints:XML::parse_url($url, $no_expand)

Return a DOM document found at the URL

$url - the url which resolves to the XML you wish to parse.

$no_expand - set to 1 if you do not want the xml to be indented.

User Comments