NAME
XML::Merge - flexibly merge XML documents
VERSION
This documentation refers to version 1.2.565EgGd of XML::Merge, which was released on Sun Jun 5 14:42:16:39 2005.
SYNOPSIS
use XML::Merge;
# create new XML::Merge object from MainFile.xml
my $merge_obj = XML::Merge->new('filename' => 'MainFile.xml');
# Merge File2Add.xml into MainFile.xml
$merge_obj->merge( 'filename' => 'File2Add.xml');
# Tidy up the indenting that resulted from the merge
$merge_obj->tidy();
# Write out changes back to MainFile.xml
$merge_obj->write();
DESCRIPTION
This module inherits from XML::Tidy which in turn inherits from XML::XPath. This ensures that Merge objects' indenting can be tidied up after any merge operation since such modification usually spells the ruination of indentation. Polymorphism allows Merge objects to be utilized as normal XML::XPath objects as well.
The merging behavior is setup to combine separate XML documents according to certain rules && configurable options. If both documents have root nodes which are elements of the same name, the documents are merged directly. Otherwise, one is merged as a child of the other. An optional XPath location can be specified as the place to perform the merge. If no location is specified, the merge is attempted at the first matching element or is appended as the new last child of the other root if no match is found.
2DO
USAGE
new()
This is the standard Merge object constructor. It can take the same
parameters as an XML::XPath object constructor to initialize the primary
XML document object (the object which subsequent XML documents will be
merged into). These parameters can be any one of:
'filename' => 'SomeFile.xml'
'xml' => $variable_which_holdsabunch_of_XML_data
'ioref' => $file_InputOutput_reference
'context' => $existing_node_at_specified_context_to_become_new_obj
Merge's new() can also accept merge-option parameters to override the default merge behavior. These include:
'conflict_resolution_method' => 'main', # main file wins
'conflict_resolution_method' => 'merg', # merge file wins
# 'last-in_wins' is an alias for 'merg'
'conflict_resolution_method' => 'warn', # croak conflicts
'conflict_resolution_method' => 'test', # just test, 0 if conflict
# this option is not implemented yet, please say if you need it
'comment_join_method' => 'none',
merge()
The merge() member function can accept the same XML::XPath constructor
options as new() but this time they are for the temporary file which
will be merged into the main object. Merge-options from new() can also
be specified && they will only impact one particular invokation of
merge(). The specified document will be merged into the primary XML
document object according to the following default merge rules:
0. If both documents share the same root element name, they are
merged directly.
1. If they don't share root elements but the temporary merge file's
root element is found anywhere within the main file, the merge
occurs at the match.
2. If no root element match is found, the merge document becomes the
new last child of the main file's root element.
3. Whenever a deeper level is found with an element of the same name
in both documents && either it does not contain any
distinguishing attributes or it has attributes which are
recognized as 'identifier' (id) attributes (by default, for any
element, these are attributes named: 'id', 'name', && 'handle'),
a corresponding element is searched for to match && merge with.
4. Any remaining (non-id) nodes are merged in document order.
5. When a conflict arises as non-id attributes or other nodes merge,
the specified conflict_resolution_method merge-option is
applied (which by default has the main file data persist at the
expense of the merging file data).
Some of the above rules can be overridden first by the object's merge-options && second by the particular method call's merge-options. Thus, if the default merge-option for conflict resolution is to have the main object win && you use the following constructor:
my $merge_obj = XML::Merge->new(
'filename' => 'MainFile.xml',
'conflict_resolution_method' => 'last-in_wins');
... then any $merge_obj->merge() call would override the default merge behavior by letting the document being merged have priority over the main object's document. However, you could supply additional merge-options in the parameter list of your specific merge() call like:
$merge_obj->merge(
'filename' => 'File2Add.xml',
'conflict_resolution_method' => 'warn');
... then the latest option would override the already overridden.
The 'test' conflict_resolution_method merge-option does not modify the object at all. It solely returns true if no conflict is encountered. It should be used like:
foreach(@files) {
if($merge_obj->merge('cres' => 'test', $)) {
$mergeobj->merge($_); # only do it if there are no conflicts
} else {
croak("Yipes! Conflict with file:$_!\n");
}
}
merge() can also accept another XML::Merge object as a parameter for what to be merged with the main object instead of a filename. An example of this is:
$merge_obj->merge($another_merge_obj);
Along with the merge options that can be specified in the object constructor, merge() also accepts the following options to specify where to perform the merge relative to:
'merge_destination_path' => $main_obj_xpath_location,
'merge_source_path' => $merging_obj_xpath_location,
unmerge()
The unmerge() member function is a shorthand for calling both write() &&
prune() on a certain XPath location which should be written out to a
disk file before being removed from the Merge object. Please see
XML::Tidy for documentation of the inherited write() && prune() member
functions.
This unmerge() process could be the opposite of merge() if no original elements or attributes overlapped && combined but if combining did happen, this would remove original sections of your primary XML document's data from your Merge object so please use this carefully. It is meant to help separate a giant object (probably the result of myriad merge() calls) back into separate useful well-formed XML documents on disk.
unmerge() takes a filename && an xpath_location parameter.
Accessors
get_object_to_merge()
Returns the object which was last merged into the main object.
set_object_to_merge()
Assigns the object which was last merged into the main object.
get_conflict_resolution_method()
Returns the underlying merge-option conflict_resolution_method.
set_conflict_resolution_method()
A new value can be provided as a parameter to be assigned as the
XML::Merge object's merge-option.
get_comment_join_method()
Returns the underlying merge-option comment_join_method.
set_comment_join_method()
A new value can be provided as a parameter to be assigned as the
XML::Merge object's merge-option.
get_id_xpath_list()
Returns the underlying id_xpath_list. This is normally just a list of
attributes (eg. '@id', '@name', '@handle') which are unique identifiers
for any XML element. When these attribute names are encountered during a
merge(), another element with the same name && attribute value are
matched for further merging && conflict resolution.
set_id_xpath_list()
A new list can assigned to the XML::Merge object's id_xpath_list.
Please note that this list normally contains XPath attributes so they must be preceded by an at-symbol (@) like: '@example_id_attribute'.
CHANGES
Revision history for Perl extension XML::Merge:
INSTALL
From your command shell, please run:
`perl -MCPAN -e "install XML::Merge"`
or uncompress the package && run the standard:
`perl Makefile.PL; make; make test; make install`
FILES
XML::Merge requires:
Carp to allow errors to croak() from calling sub
XML::Tidy to use objects derived from XPath to update XML
LICENSE
Most source code should be Free! Code I have lawful authority over is && shall be! Copyright: (c) 2004, Pip Stuart. Copyleft : This software is licensed under the GNU General Public License (version 2), && as such comes with NO WARRANTY. Please consult the Free Software Foundation (http://FSF.Org) for important information about your freedom.
AUTHOR
Pip Stuart <Pip@CPAN.Org>