Michael Carman > Tk-DiffText > Tk::DiffText

Download:
Tk-DiffText-0.19.zip

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.19   Source  

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.

syntax highlighting: