NAME

Tk::DiffText - Perl/Tk composite widget for colorized diffs.

SYNOPSIS

  use Tk::DiffText;

  my $w = $mw->DiffText()->pack();

  $w->diff($file0, $file1);

DESCRIPTION

This module defines a composite widget that makes it simple to provide basic "diff" functionality to your Tk applications.

OPTIONS

-orient => 'horizontal'|'vertical'

Controls the arrangement of the text panes. Defaults to vertical.

-gutter => 0|1

Hides and displays the line number gutter. Defaults to 1.

-gutterforeground => color

Sets the gutter foreground color.

-gutterbackground => color

Sets the gutter background color.

-diffcolors => {...}

Sets the colors used for highlighting diff results. The structure of the value hash is as follows:

  {
    add => [-fg => 'green'  ],               # tag for additions
    del => [-fg => 'red', -overstrike => 1], # tag for deletions
    mod => [-fg => 'blue'   ],               # tag for changes
    pad => [-bg => '#f0f0f0'],               # tag for blank line padding
    cur => [-bg => 'yellow'],                # tag for navigation
  }

For each of the tags you can specify any option that is valid for use in a ROText widget tag: -foreground, -background, -overstrike, etc.

-map => 'scaled'|'scrolled'|'none'

Controls the display and type of difference map. Defaults to scaled.

The difference map will match its colors to those from -diffcolors by default. It uses the background color if specified, otherwise it uses the foreground color.

METHODS

load

  $w->load(a => I<data>);
  $w->load(b => I<data>);

Load data into frames a (top or left) and b (bottom or right), respectively.

Normally data is a filename but it can also be a reference to an array of lines of data, a string containing a slurped file, an open filehandle, a glob (which is interpreted as a filehandle), an IO::File object or any other object with a getline method.

Returns true on success, false otherwise.

compare

  $w->compare(
        -case        => 0,
        -whitespace  => 0,
        -keygen      => \&makekey,
        -granularity => 'line', # or 'word' 'char' or regexp
  );

Compares the data in the text frames and highlights the differences.

Setting either -case or -whitespace to 0 instructs the diff algorithm to ignore case and whitespace, respectively.

You can provide your own key generation function via the -keygen argument. This overrides the -case and -whitespace options, so you'll have to build that functionality into your function if you want it. See Algorithm::Diff for more details on key generation functions.

The -granularity option controls the level of detail at which the diff is performed. The default value, 'line,' shows differences between lines. Changing it to 'word' or 'char' will show differences within a line at the word or character level. You may also pass a qr// quoted regular expression or a string which will be interpreted as a regular expression.

Note: For performance reasons, diffs are always performed line-by-line first. Finer granularity settings are only applied to lines marked as changed by the initial comparison. This can lead to slightly different results than you would get if you did a single diff at the higher level of resolution. (The results aren't wrong, just different.)

diff Deprecated

  $w->diff($data1, $data2, -case => 0);

Equivalent to:

  $w->load(a => $data1);
  $w->load(b => $data1);
  $w->compare(-case => 0);

This method has been deprecated and may be removed in future versions.

first

Highlights the first difference and scrolls to bring it in view.

prev

Highlights the previous difference and scrolls to bring it in view.

next

Highlights the next difference and scrolls to bring it in view.

last

Highlights the last difference and scrolls to bring it in view.

NOTES

Unicode

Tk::DiffText supports Unicode provided that your versions of Perl (5.8+) and Tk (804+) do. To compare Unicode files, open the files with the appropriate IO layer and pass load the filehandles.

  open(my $fha, '<:utf8', $file_a) or die;
  open(my $fhb, '<:utf8', $file_b) or die;
  
  $w->load(a => $fha);
  $w->load(b => $fhb);

BUGS

Some configuration settings (-gutter, -orient, -diffcolors, -map) are only valid at creation time and cannot be changed later.

The line numbers in the gutter can get out of sync with the file display if you set -wrap to something other than 'none' (so don't do that).

AUTHOR

Michael J. Carman <mjcarman@mchsi.com>

COPYRIGHT AND LICENSE

Copyright (C) 2006,2008 by Michael J. Carman

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

cpanm Tk::DiffText

perl -MCPAN -e shell
install Tk::DiffText