/ 
XML-DifferenceMarkup-1.05
River stage zero No dependents
/ XML::DifferenceMarkup

NAME

XML::DifferenceMarkup - XML diff and merge

SYNOPSIS

use XML::DifferenceMarkup qw(make_diff);
use XML::LibXML;

$parser = XML::LibXML->new(keep_blanks => 0, load_ext_dtd => 0);
$d1 = $parser->parse_file($fname1);
$d2 = $parser->parse_file($fname2);

$dom = make_diff($d1, $d2);
print $dom->toString(1);

DESCRIPTION

This module implements an XML diff producing XML output. Both input and output are DOM documents, as implemented by XML::LibXML.

The diff format used by XML::DifferenceMarkup is meant to be human-readable (i.e. simple, as opposed to short) - basically the diff is a subset of the input trees, annotated with instruction element nodes specifying how to convert the source tree to the target by inserting and deleting nodes. To prevent name colisions with input trees, all added elements are in a namespace http://www.locus.cz/diffmark (the diff will fail on input trees which already use that namespace).

The top-level node of the diff is always <diff/> (or rather <dm:diff xmlns:dm="http://www.locus.cz/diffmark"> ... </dm:diff> - this description omits the namespace specification from now on); under it are fragments of the input trees and instruction nodes: <insert/>, <delete/> and <copy/>. <copy/> is used in places where the input subtrees are the same - in the limit, the diff of 2 identical documents is

<?xml version="1.0"?>
<dm:diff xmlns:dm="http://www.locus.cz/diffmark">
  <dm:copy count="1"/>
</dm:diff>

(copy always has the count attribute and no other content). <insert/> and <delete/> have the obvious meaning - in the limit a diff of 2 documents which have nothing in common is something like

<?xml version="1.0"?>
<dm:diff xmlns:dm="http://www.locus.cz/diffmark">
  <dm:delete>
    <old/>
  </dm:delete>
  <dm:insert>
    <new>
      <tree>with the whole subtree, of course</tree>
    </new>
  </dm:insert>
</dm:diff>

A combination of <insert/>, <delete/> and <copy/> can capture any difference, but it's sub-optimal for the case where (for example) the top-level elements in the two input documents differ while their subtrees are exactly the same. This case is handled by putting the element from the second document into the diff, adding to it a special attribute dm:update (whose value is the element name from the first document) marking the element change:

<?xml version="1.0"?>
<dm:diff xmlns:dm="http://www.locus.cz/XML/diffmark">
  <top-of-second dm:update="top-of-first">
    <dm:copy count="42"/>
  </top-of-second>
</dm:diff>

<delete/> contains just one level of nested nodes - their subtrees are not included in the diff (but the element nodes which are included always come with all their attributes). <insert/> and <delete/> don't have any attributes and always contain some subtree.

Instruction nodes are never nested; all nodes above an instruction node (except the top-level <diff/>) come from the input trees. A node from the second input tree might be included in the output diff to provide context for instruction nodes when it's an element node whose subtree is not the same in the two input documents. When such an element has the same name, attributes (names and values) and namespace declarations in both input documents, it's always included in the diff (its different output trees guarantee that it will have some chindren there). If the corresponding elements are different, the one from the second document might still be included, with an added dm:update attribute, provided that both corresponding elements have non-empty subtrees, and these subtrees are so similar that deleting the first corresponding element and inserting the second would lead to a larger diff. And if this paragraph seems too complicated, don't despair - just ignore it and look at some examples.

FUNCTIONS

Note that XML::DifferenceMarkup functions must be explicitly imported (i.e. with use XML::DifferenceMarkup qw(make_diff merge_diff);) before they can be called.

make_diff

make_diff takes 2 parameters (the input documents) and produces their diff. Note that the diff is asymmetric - make_diff($a, $b) is different from make_diff($b, $a).

merge_diff

merge_diff takes the first document passed to make_diff and its return value and produces the second document. (More-or-less - the document isn't canonicalized, so opinions on its "equality" may differ.)

Error Handling

Both make_diff and merge_diff throw exceptions on invalid input - their own exceptions as well as exceptions thrown by XML::LibXML. These exceptions can usually (probably not always, though - it used to be possible to construct an input which would crash the calling process) be catched by calling the functions from an eval block.

BUGS

  • information outside the document element is not processed

AUTHOR

Vaclav Barta <vbar@comp.cz>

SEE ALSO

XML::LibXML