API:EPrints/XML
EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
Contents
- 1 NAME
- 2 SYNOPSIS
- 3 METHODS
- 3.1 Parsing
- 3.2 Node Creation
- 3.3 Other
- 3.3.1 is
- 3.3.2 clone
- 3.3.3 clone_node
- 3.3.4 clone_node
- 3.3.5 contents_of
- 3.3.6 text_contents_of
- 3.3.7 to_string
- 3.3.8 to_string
- 3.3.9 dispose
- 3.3.10 parse_xml
- 3.3.11 event_parse
- 3.3.12 is_dom
- 3.3.13 clone_and_own
- 3.3.14 make_document
- 3.3.15 write_xml_file
- 3.3.16 write_xhtml_file
- 3.3.17 tidy
- 3.3.18 namespace
- 3.3.19 version
NAME
EPrints::XML - XML Abstraction Module
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.
METHODS
Parsing
parse_string
$doc = $xml->parse_string( $string, %opts )
Returns an XML document parsed from $string.
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
parse_url
$doc = $xml->parse_url( $url, %opts )
Returns an XML document parsed from the content located at $url.
Node Creation
create_element
$node = $xml->create_element( $name [, @attrs ] )
Returns a new XML element named $name with optional attribute pairs @attrs.
create_cdata_section
$node = $xml->create_cdata_section( $value )
Returns a CDATA section containing $value.
create_text_node
$node = $xml->create_text_node( $value )
Returns a new XML text node containing $value.
create_comment
$node = $xml->create_comment( $value )
Returns a new XML comment containing $value.
create_document_fragment
$node = $xml->create_document_fragment
Returns a new XML document fragment.
Other
is
$bool = $xml->is( $node, $type [, $type ... ] )
Returns true if $node is one of the given node types: Document, DocumentFragment, Element, Comment, Text.
clone
$node = $xml->clone( $node )
Returns a deep clone of $node. The new node(s) will be owned by this object.
clone_node
$node = $xml->clone_node( $node )
Returns a clone of $node only (no children). The new node will be owned by this object.
clone_node
$node = EPrints::XML::clone_node( $node [, $deep ] )
DEPRECATED.
contents_of
$node = $xml->contents_of( $node )
Returns a document fragment containing a copy of all the children of $node.
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).
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
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 />
dispose
$xml->dispose( $node )
Dispose and free the memory used by $node.
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.
event_parse
event_parse( $fh, $handler )
Parses the XML from filehandle $fh, calling the appropriate events in the handler where necessary.
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.
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.
make_document
$document = EPrints::XML::make_document()
Create and return an empty document.
write_xml_file
EPrints::XML::write_xml_file( $node, $filename )
Write the given XML node $node to file $filename.
write_xhtml_file
EPrints::XML::write_xhtml_file( $node, $filename )
Write the given XML node $node to file $filename with an XHTML doctype.
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.
namespace
$namespace = EPrints::XML::namespace( $thing, $version )
Return the namespace for the given version of the eprints xml.
version
$v = EPrints::XML::version()
Returns a string description of the current XML library and version.
