NAME

String::ShowDiff - Perl extension to help visualize differences between strings

SYNOPSIS

  use String::ShowDiff qw/ansi_colored_diff/;
  print ansi_colored_diff("abcehjlmnp", "bcdefjklmrst");

  # or a bit more detailed:
  my %options = ('u' => 'reset',
                 '+' => 'on_green',
                         '-' => 'on_red');
  print ansi_colored_diff($oldstring, $newstring, \%options);

  # or let's see only the changed words 
  print ansi_colored_diff($old, $new, {context => qr/\w*/, gap => ' '});

DESCRIPTION

This module is a wrapper around the diff algorithm from the module Algorithm::Diff. It's job is to simplify a visualization of the differences of each strings.

Compared to the many other Diff modules, the output is neither in diff-style nor are the recognised differences on line or word boundaries, they are at character level.

FUNCTIONS

ansi_colored_diff $string, $changed_string, $options_hash;

This method compares $string with $changed_string and returns a string for an output on an ANSI terminal. Removed characters from $string are shown by default with a red background, while added characters to $changed_string are shown by default with a green background (the unchanged characters are shown with the default values for the terminal).

The $options_hash allows you to set the colors for the output and the context to be shown. The variable is a reference to a hash with the optional keys: 'u' for the color of the unchanged parts, '-', '+' for the color of the removed and the added parts, 'context' for a regexp specifying the context that shall be shown before and after a changed part and 'gap' for the string that shall be shown between the contexts of two changings. The default values for the options are:

    my $default_options = {
        'u'       => 'reset',
        '-'       => 'on_red',
        '+'       => 'on_green',
    'context' => qr/.*/,
    'gap'     => '',
    };

The specified colors must follow the conventions for the colored method of Term::ANSIColor. Please read its documentation for details.

The specified context must be a valid regexp, constructed with the qr/.../ operator (or alternatively a string defining a valid regexp). Internal the context around a changing is created with matching the preceding substring with /($context_re)$ and the succeeding substring with ^($context_re). That is important to know if you want to work with backreferences. As an additional group encloses your regexp pattern, the first of your own defined subgroup is in $2 instead of $1. (That's not very nice, but still better than paying the price of using $&).

The gap parameter describes how to fill the gap between two shown changings in their context. Here are some examples of these parameters:

    print ansi_colored_diff($s1, $s2, {context => qr/.*/, gap => ''}); # default
    # will print the complete combined string with the marked removings and
    # additions

    print ansi_colored_diff($s1, $s2, {context => qr/.{0,3}/, gap => ' ... '});
    # will print all changings with a context of the left and right 3 chars
    # and will join each of them with a space, 3 dots and a space
    # Note that it is important to use qr/.{0,3}/ instead of qr/.../ to also
    # show only a context of 0,1 or 2 chars at the beginning or end of the
    # strings

    print ansi_colored_diff($s1, $s2, {context => qr/\w*/, gap => ' '})
    # will print all changed words and seperates them with a blank
    

EXPORT

None by default.

SEE ALSO

Term::ANSIColor

Algorithm::Diff, Text::Diff, Text::ParagraphDiff, Test::Differences

AUTHOR

Janek Schleicher, <bigj@kamelfreund.de>

COPYRIGHT AND LICENSE

Copyright 2003 by Janek Schleicher

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