NAME

Text::Diff3 - three way text comparison and merging.

VERSION

0.10

SYNOPSIS

    # in default, this module does not export any symbol.
    use Text::Diff3;
    use Text::Diff3 qw(:all);
    use Text::Diff3 qw(diff3 merge diff);
    
    my $mytext   = [map {chomp; $_} <$input0>]);
    my $original = [map {chomp; $_} <$input1>]);
    my $yourtext = [map {chomp; $_} <$input2>]);
    
    my $diff3 = diff3($mytext, $origial, $yourtext);
    for my $r (@{$diff3}) {
        printf "%s %d,%d %d,%d %d,%d\n", @{$r};
        # lineno start from not zero but ONE!
        for my $lineno ($r->[1] .. $r->[2]) {
            print $mytext->[$lineno - 1], "\n";
        }
        for my $lineno ($r->[3] .. $r->[4]) {
            print $yourtext->[$lineno - 1], "\n";
        }
        for my $lineno ($r->[5] .. $r->[6]) {
            print $original->[$lineno - 1], "\n";
        }
    }
    
    my $merge = merge($mytext, $origial, $yourtext);
    if ($merge->{conflict}) {
        print STDERR "conflict\n";
    }
    for my $line (@{$merge->{body}}) {
        print "$line\n";
    }
    
    my $diff = diff($original, $mytext);
    for my $r (@{$diff}) {
        printf "%s%s%s\n",
            $r->[1] >= $r->[2] ? $r->[1] : "$r->[1],$r->[2]",
            $r->[0],
            $r->[3] >= $r->[4] ? $r->[3] : "$r->[3],$r->[4]";
        if ($r->[0] ne 'a') { # delete or change
            for my $lineno ($r->[1] .. $r->[2]) {
                print q{-}, $original->[$lineno - 1], "\n";
            }
        }
        if ($r->[0] ne 'd') { # append or change
            for my $lineno ($r->[3] .. $r->[4]) {
                print q{+}, $mytext->[$lineno - 1], "\n";
            }
        }
    }
    
    # component style (deprecated. no longer maintenance)
    use Text::Diff3 qw(:factory);

DESCRIPTION

This module provides you to compute difference sets between two or three texts ported from GNU diff3.c written by R. Smith.

For users convenience, Text::Diff3 includes small diff procedure based on the P. Heckel's algorithm. On the other hands, many other systems use the popular Least Common Sequence (LCS) algorithm. The merits for each algorithm are case by case. In author's experience, two algorithms generate almost same results for small local changes in the text. In some cases, such as moving blocks of lines, it happened quite differences in results.

FUNCTIONS

diff3(\@mytext, \@origial, \@yourtext)

Calcurate three-way differences. This returns difference sets as an array reference.

For example,

    my $diff3 = Text::Diff3::Lite::diff3(
        [qw(A A b c     f g h i j K l m n O p Q R s)],
        [qw(a   b c d e f g h i j k l m n o p q r s)],
        [qw(a   b c d   f       j K l M n o p 1 2 s t u)],
    );

returns a following reference:

    [
        [0,    1, 2,  1, 1,  1, 1],
        ['A',  5, 4,  4, 4,  4, 5],
        [1,    6, 8,  6, 5,  7, 9],
        [2,   10,10,  7, 7, 11,11],
        [1,   12,12,  9, 9, 13,13],
        [0,   14,14, 11,11, 15,15],
        ['A', 16,17, 13,14, 17,18],
        [1,   19,18, 16,17, 20,19],
    ]

where

    case $diff3->[$i][0]
    when 0: changes by my text.
    when 1: changes by your text.
    when 2: changes from original text.
    when 'A': conflict!
    end

merge(\@mytext, \@origial, \@yourtext)

Merge changes by my or your texts on the original text. This returns an hash reference.

For example,

    my $merge = Text::Diff3::Lite::merge(
        [qw(A A b c     f g h i j K l m n O p Q R s)],
        [qw(a   b c d e f g h i j k l m n o p q r s)],
        [qw(a   b c d   f       j K l M n o p 1 2 s t u)],
    );

returns a following reference:

    {
        'conflict' => 1,
        'body' => [
            qw(A A b c f j K l M n O p),
            '<<<<<<<',
            'Q',
            'R',
            '|||||||',
            'q',
            'r',
            '=======',
            '1',
            '2',
            '>>>>>>>',
            qw(s t u),
        ],
    }

diff(\@original, \@mytext)

Calcurate two-way differences. This returns difference sets as an array reference.

For example,

    my $diff = Text::Diff3::Lite::diff(
        [qw(a b c     f g h i j)],
        [qw(a B c d e f       j)],
    );

returns a following reference:

    [
        [qw(c 2 2 2 2)],
        [qw(a 4 3 4 5)],
        [qw(d 5 7 7 6)],
    ]

where

    case $diff->[$i][0]
    when 'a': append.
    when 'c': change.
    when 'd': delete.
    end

VARIABLE

$DIFF_PROC

This holds a two-way diff procedure used in function style diff3. Please change this as your like.

    $Text::Diff3::DIFF_PROC = sub {
        my($origtext, $mytext) = @_;
        # origtext => ['line1', 'line2', 'line3', ...];
        # mytext => ['line1', 'line2', 'line3', ...];
        
        # calcurate two way differences.
        
        # for example:
        my $diff_list = [
            [qw(c 2 2 2 2)],
            [qw(a 4 3 4 5)],
            [qw(d 5 7 7 6)],
        ];
        # where line numbers start from 1.
        return $diff_list;
    };

SEE ALSO

GNU/diffutils/2.7/diff3.c

   Three way file comparison program (diff3) for Project GNU.
   Copyright (C) 1988, 1989, 1992, 1993, 1994 Free Software Foundation, Inc.
   Written by Randy Smith

P. Heckel. ``A technique for isolating differences between files.'' Communications of the ACM, Vol. 21, No. 4, page 264, April 1978.

AUTHOR

MIZUTANI Tociyuki <tociyuki@gmail.com>.

LICENSE AND COPYRIGHT

Copyright (C) 2011 MIZUTANI Tociyuki

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.