[manpage_begin DiffUtil n 0.4.0]
[copyright {2010, Peter Spjuth}]
[moddesc   {Comparision Utilities}]
[titledesc {Compare Stuff}]
[require Tcl 8.6]
[require DiffUtil [opt 0.4.0]]
[description]
[para]

This package provides utilites for comparisons of strings, lists
and files.
The base comparison is a Longest Common Substring algorithm based
on J. W. Hunt and M. D. McIlroy, "An algorithm for differential
file comparison," Comp. Sci. Tech. Rep. #41, Bell Telephone
Laboratories (1976). Available on the Web at the second
author's personal site: http://www.cs.dartmouth.edu/~doug/

[section COMMANDS]

[list_begin definitions]

[call [cmd "::DiffUtil::diffFiles"] \
        [opt [arg options]] [arg file1] [arg file2]]

Compare two files line by line.
The return value depends on the [arg -result] option, see below.

[list_begin options]

[opt_def -nocase]
Ignore case.

[opt_def -i]
Ignore case.

[opt_def -b]
Ignore space changes. Any sequence of whitespace is treated as a single
space, except at beginning of line where it is completely ignored.

[opt_def -w]
Ignore all spaces.

[opt_def -noempty]
Ignore empty lines in initial compare step. I.e. empty lines are considered
not equal at first. Multiple equal lines gives longer runtimes and by avoiding
the very common empty line, runtimes are improved. With [arg -b] or [arg -w],
all-space lines are considered empty. This is similar to having a [arg -pivot]
value of 1 just for empty lines.

[opt_def -pivot [arg value]]
Ignore common lines in initial compare step. Multiple equal lines gives longer
runtime and by avoiding them runtime is improved.  The pivot [arg value]
says how many equal lines there at most may be in [arg file2] for those
lines to be regarded. The default is 10.

[opt_def -nodigit]
Consider any sequence of digits equal.

[opt_def -align [arg list]]
Align lines. The argument is a list with an even number of elements. Each
pair is line numbers in the first and second file. Those lines are considered
equal and matching, regardless of their contents.

[opt_def -range [arg list]]
Diff only a range of the files. The list is {first1 last1 first2 last2}

[opt_def -regsub [arg list]]
Apply a search/replace regular expression before comparing. The list consists
of an even number of elements. Each pair is a regular expression and a
substitution, as used in [cmd "regsub -all"]. Multiple pairs are allowed
and multiple [arg -regsub] are allowed. All patterns will be applied in order
on each line.

[opt_def -regsubleft [arg list]]
Like [arg -regsub] but only applied to the first file.

[opt_def -regsubright [arg list]]
Like [arg -regsub] but only applied to the second file.

[opt_def -result [arg style]]
Select result style. The default is [arg diff].
[list_begin definitions]
[def [const diff]]
Returns a list of differences, each in a four element list.
{LineNumber1 NumberOfLines1 LineNumber2 NumberOfLines2}
The first line in a file is number 1.
[def [const match]]
The return value is a list of two lists of equal length. The first
sublist is of line numbers in [arg file1], and the second sublist is
of line numbers in [arg file2].  Each corresponding pair of line numbers
corresponds to equal lines in the files.
[list_end]

[opt_def -encoding [arg encoding]]
Apply encoding when reading files. This works as for [cmd fconfigure].
[opt_def -translation [arg value]]
Apply translation when reading files. This works as for [cmd fconfigure].
[opt_def -gz]
Apply gunzip decompression when reading files. Requires zlib.

[list_end]

[call [cmd "::DiffUtil::diffLists"] \
        [opt [arg options]] [arg list1] [arg list2]]

Compare two lists element by element.
The return value depends on the [arg -result] option, see below.

[list_begin options]

[opt_def -nocase]
Ignore case.

[opt_def -i]
Ignore case.

[opt_def -b]
Ignore space changes.

[opt_def -w]
Ignore all spaces.

[opt_def -noempty]
Ignore empty elements in initial compare step. I.e. empty elements are considered
not equal at first. Multiple equal elements give longer runtimes and by avoiding
the very common empty element, runtimes are improved. With [arg -b] or [arg -w],
all-space elements are considered empty.
Empty elements that obviously matches are noted as equal in a post processing
step, but empty elements within change blocks will be reported as changes.

[opt_def -nodigit]
Consider any sequence of digits equal.

[opt_def -result [arg style]]
Select result style. The default is [arg diff].
[list_begin definitions]
[def [const diff]]
Returns a list of differences, each in a four element list.
{ElementIndex1 NumberOfElements1 ElementIndex2 NumberOfElements2}
[def [const match]]
The return value is a list of two lists of equal length. The first
sublist is of indices in [arg list1], and the second sublist is
of indices in [arg list2].  Each corresponding pair of indices
corresponds to equal elements in the sequences.
[list_end]

[list_end]

[list_end]

[section EXAMPLES]

[para]
[example {
% DiffUtil::diffFiles $file1 $file2
{{3 2 3 4}}
}]

[keywords diff lcs {longest common substring}]
[manpage_end]
