
=begin pod

=NAME
Date::Dump::Tree::Diff - Renders two data structures in synch

=SYNOPSIS
	
=DESCRIPTION

Data::Dump::Tree::Diff is a Role you can add to a Data::Dump::Tree object

The role add a B<dump_synched> method to the object that can: 

=item can display two data structures side by side

=item can display the difference between two data structures


=INTERFACE

=item method get_synched_dump($s1, $s2, *%options) 

Dumps of the synchronized structures on the terminal

=USAGE

	$d.dump_synched(
		# data structures to dump
		%df1,%df2,

		#options to be used on both sides of the dump
		does => (DDTR::MatchDetails,), color_glyphs => True,

		#options specific to the synchronized dump 
		diff_glyphs => False, compact_width => True,
		remove_eq => True, remove_eqv => True) ;

=head2 Output example
	
	{8} @0                                       ~  {7} @0 
	|- A => {5} @1                              === |- A => {5} @1 
	|  |- a => 1 / "1".IntStr                   === |  |- a => 1 / "1".IntStr  
	|  |- b => 2 / "2".IntStr                   === |  |- b => 2 / "2".IntStr  
	|  |- c => 3 / "3".IntStr                   === |  |- c => 3 / "3".IntStr  
	|  |- d => {1} @2                           === |  |- d => {1} @2 
	|  |  `- x => {1} @3                        === |  |  `- x => {1} @3 
	|  |     `- y => 1 / "1".IntStr             === |  |     `- y => 1 / "1".IntStr  
	|  `- e => 1.Int                            === |  `- e => 1.Int  
	|- B => {3} @4                               ~  |- B => {5} @4 = @1 
	|  |- a => 1 / "1".IntStr                   eqv |  |- a => 1 / "1".IntStr  
	|  |- b => 2 / "2".IntStr                   eqv |  |- b => 2 / "2".IntStr  
	|  |- c => 3 / "3".IntStr                   eqv |  |- c => 3 / "3".IntStr  
	|  |- d (-)                                  [r |  |- d => {1} @5 = @2 
	|  `- e (-)                                  !  |  `- e => 1.Int  
	|- C => {3} @5                              eqv |- C => {3} @6 
	|  |- a => 1 / "1".IntStr                   eqv |  |- a => 1 / "1".IntStr  
	|  |- b => 2 / "2".IntStr                   eqv |  |- b => 2 / "2".IntStr  
	|  `- c => 3 / "3".IntStr                   eqv |  `- c => 3 / "3".IntStr  
	|- D => 0.3 (3/10).Rat                       !  |- D => hi.Str  
	|- E => 1.Int                               !=  |- E => 2.Int  
	|- F => 2.Int                                [r |- F => {3} @7 
	|                                            [r |  |- a => 1 / "1".IntStr  
	|                                            [r |  |- b => 2 / "2".IntStr  
	...

=head2 Configuration and Overrides
Check B<Data::Dump::Tree> for the options that you can pass the dumper. The
same options will be used on both sides of the dump. All the Data::Dump::Tree
options are valid 

=head3 title
You can eiter set the title for both sides simulteanously or for each side
using:

=item lhs_title

=item rhs_title

=head3 Width
By default the terminal width will be divided in two, minus the room for
the diff glyphs column. You can also set option I<width> or use

=item compact_width
Put the two data structures as close to each other as possible

The default glyphs are:

	same_object          => '===',
	same_type_same_value => 'eqv',
	same_type_diff_value => '!= ',
	different_type       => ' ! ',
	same_container       => ' ~ ',
	diff_container       => '!~!',
	container_left       => ' [r',
	container_right      => 'l] ',
	only_lhs             => 'l  ',
	only_rhs             => '  r' ;

=item diff_glyphs 
You can set this  option to False if you do not want the diff glyph column
to be displayed.

=head3 Displaying only the difference between the data structures
Below is an example where only different elements are displayed; the diff
glyphs column was also removed from the dump. The example can be found in
I<examples/diff>.

	{8} @0                       {7} @0 
	|- B => {3} @4               |- B => {5} @4 = @1 
	|  |- d (-)                  |  |- d => {1} @5 = @2 
	|  `- e (-)                  |  `- e => 1.Int  
	|- D => 0.3 (3/10).Rat       |- D => hi.Str  
	|- E => 1.Int                |- E => 2.Int  
	|- F => 2.Int                |- F => {3} @7 
	|                            |  |- a => 1 / "1".IntStr  
	|                            |  |- b => 2 / "2".IntStr  
	|                            |  `- c => 3 / "3".IntStr  
	|- G => {1} @6               |- G (-)  
	|  `- a => 1 / "1".IntStr    |  

You can set

=item remove_eq 
set if you want the to remove from the display the objects that are exactely
the same in both data structures.
 
=item $remove_eqv
set if you want the to remove from the display the objects that are equivalent 
in both data structures.

=head3 data structure filters

you can set U<header_filters>, U<elements_filters>, and U<footer_filters> as
described in U<Data::Dump::Tree> documentation.

You can alsospecify filters that are specific to a side of the diff

=item rhs_header_filters and lhs_header_filters

=item rhs_elements_filters and lhs_elements_filters

=item rhs_footer_filters and lhs_footer_filters


=head3 diff synchronization filter 
I<Data::Dump::Tree::Diff> synchronizes Hashes, if you want to synch other type
of data you can set 

=item diff_synch_filter
 
Note that you will have to synch Hashes too if you want to keep them ordered
properly.

=AUTHOR

Nadim ibn hamouda el Khemir
https://github.com/nkh

=LICENSE

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl6 itself.

=SEE-ALSO

Data::Dump::Tree

=end pod

DOC INIT {use Pod::To::Text ; pod2text($=pod) ; }

