Difference between revisions of "API:EPrints/XML"

From EPrints Documentation
Jump to: navigation, search
 
Line 8: Line 8:
 
'''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%; '>
 
<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= -->
 +
<!-- Pod2Wiki=head_synopsis -->
 +
==SYNOPSIS==
 +
<source lang="perl">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 );</source>
  
 
 
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=head_synopsis -->
 
==SYNOPSIS==
 
  my $xml = $repository-&gt;xml;
 
 
 
  $doc = $xml-&gt;parse_string( $string );
 
  $doc = $xml-&gt;parse_file( $filename );
 
  $doc = $xml-&gt;parse_url( $url );
 
 
 
  $utf8_string = $xml-&gt;to_string( $dom_node, %opts );
 
 
 
  $dom_node = $xml-&gt;clone( $dom_node ); # deep
 
  $dom_node = $xml-&gt;clone_node( $dom_node ); # shallow
 
 
 
  # clone and return child nodes
 
  $dom_node = $xml-&gt;contents_of( $dom_node );
 
  # Return text child nodes as a string
 
  $utf8_string = $xml-&gt;text_contents_of( $dom_node );
 
 
 
  $dom_node = $xml-&gt;create_element( $name, %attr );
 
  $dom_node = $xml-&gt;create_text_node( $value );
 
  $dom_node = $xml-&gt;create_comment( $value );
 
  $dom_node = $xml-&gt;create_document_fragment;
 
 
 
  $xml-&gt;dispose( $dom_node );
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_description -->
 
<!-- Pod2Wiki=head_description -->
 
==DESCRIPTION==
 
==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.  
 
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: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_methods -->
 
<!-- 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%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_parsing -->
 
<!-- 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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_parse_string -->
 
====parse_string====
 
 
 
  $doc = $xml-&gt;parse_string( $string, %opts )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_parse_file -->
 
====parse_file====
 
  
 
  $doc = $xml-&gt;parse_file( $filename, %opts )
 
  $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.
  
  base_path - base path to load DTD files from
+
<pre>  base_path - base path to load DTD files from
   no_expand - don't expand entities
+
   no_expand - don't expand entities</pre>
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_parse_url -->
 
====parse_url====
 
  
 
  $doc = $xml-&gt;parse_url( $url, %opts )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_node_creation -->
 
<!-- 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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_create_element -->
 
====create_element====
 
 
 
  $node = $xml-&gt;create_element( $name [, @attrs ] )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_create_data_element -->
 
====create_data_element====
 
  
 
  $node = $xml-&gt;create_data_element( $name, $value [, @attrs ] )
 
  $node = $xml-&gt;create_data_element( $name, $value [, @attrs ] )
Line 163: Line 83:
 
$value may be undef, an XML tree or an array ref of children, otherwise it is stringified and appended as a text node. Child entries are passed de-referenced to [[API:EPrints/XML#create_data_element|create_data_element]].
 
$value may be undef, an XML tree or an array ref of children, otherwise it is stringified and appended as a text node. Child entries are passed de-referenced to [[API:EPrints/XML#create_data_element|create_data_element]].
  
  $xml-&gt;create_data_element(
+
<pre>  $xml-&gt;create_data_element(
 
     "html",
 
     "html",
 
     [
 
     [
Line 172: Line 92:
 
     ],
 
     ],
 
     xmlns =&gt; "http://www.w3.org/1999/xhtml"
 
     xmlns =&gt; "http://www.w3.org/1999/xhtml"
   );
+
   );</pre>
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_create_cdata_section -->
 
====create_cdata_section====
 
  
 
  $node = $xml-&gt;create_cdata_section( $value )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_create_text_node -->
 
====create_text_node====
 
  
 
  $node = $xml-&gt;create_text_node( $value )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_create_comment -->
 
====create_comment====
 
  
 
  $node = $xml-&gt;create_comment( $value )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_create_document_fragment -->
 
====create_document_fragment====
 
  
 
  $node = $xml-&gt;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%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_other -->
 
<!-- 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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_is -->
 
====is====
 
 
 
  $bool = $xml-&gt;is( $node, $type [, $type ... ] )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_clone -->
 
====clone====
 
  
 
  $node = $xml-&gt;clone( $node )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_clone_node -->
 
====clone_node====
 
  
 
  $node = $xml-&gt;clone_node( $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_contents_of -->
 
====contents_of====
 
  
 
  $node = $xml-&gt;contents_of( $node )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_text_contents_of -->
 
====text_contents_of====
 
  
 
  $string = $xml-&gt;text_contents_of( $node )
 
  $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%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_to_string -->
 
====to_string====
 
  
 
  $utf8_string = $xml-&gt;to_string( $node, %opts )
 
  $utf8_string = $xml-&gt;to_string( $node, %opts )
Line 318: Line 135:
 
indent - if true will indent the XML tree
 
indent - if true will indent the XML tree
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce; padding: 0em 1em 0em 1em; font-size: 80%; '>
+
  $xml-&gt;dispose( $node )
<span style='display:none'>User Comments</span>
+
Dispose and free the memory used by $node.
<!-- Edit below this comment -->
 
  
 +
<!-- Pod2Wiki=head_copyright -->
 +
==COPYRIGHT==
 +
: Copyright 2000-2011 University of Southampton.
  
<!-- Pod2Wiki= -->
+
: This file is part of EPrints http://www.eprints.org/.
</div>
 
<!-- Pod2Wiki=item_dispose -->
 
====dispose====
 
  
$xml-&gt;dispose( $node )
+
: EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
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%; '>
+
: EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSESee the GNU Lesser General Public License for more details.
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
: You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
  
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=head_copyright -->
 
==COPYRIGHT==
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=_postamble_ -->
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
+
<!-- Edit below this comment -->

Latest revision as of 09:56, 22 January 2013

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.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::XML - XML Abstraction Module


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 );


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.


METHODS

Parsing

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

Returns an XML document parsed from $string.

$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
$doc = $xml->parse_url( $url, %opts )

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


Node Creation

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

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

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

Returns a new XML element named $name with $value for contents and optional attribute pairs @attrs.

$value may be undef, an XML tree or an array ref of children, otherwise it is stringified and appended as a text node. Child entries are passed de-referenced to create_data_element.

  $xml->create_data_element(
    "html",
    [
      [ "head" ],
      [ "body",
        [ [ "div", undef, id => "contents" ] ]
      ],
    ],
    xmlns => "http://www.w3.org/1999/xhtml"
  );
$node = $xml->create_cdata_section( $value )

Returns a CDATA section containing $value.

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

Returns a new XML text node containing $value.

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

Returns a new XML comment containing $value.

$node = $xml->create_document_fragment

Returns a new XML document fragment.


Other

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

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

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

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

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

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

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

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

$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).

$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

$xml->dispose( $node )

Dispose and free the memory used by $node.

COPYRIGHT

Copyright 2000-2011 University of Southampton.
This file is part of EPrints http://www.eprints.org/.
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.