Compare feature for Alpha.
Name:Compare
Version:0.3
Last update:2020-08-28 10:42:26



Introduction

The Compare library for Alpha is an always-on feature that implements powerful side-by-side file comparison, including the ability to patch differences back and forth between the two files.
It installs a submenu called Compare in the Tools menu. The items in this menu allow you to compare open windows, or selections within windows, or files on disk, or even directories.
Starting from version 9.2, Alpha has its own internal commands to execute comparisons and does not rely anymore on external software.

Basic usage

Examine the submenu Tools ↣ Compare. It contains items to compare windows, selections, files, or directories.
Use Compare ↣ Windows, Compare ↣ Selections, Compare ↣ Files…, or Compare ↣ Directories… to compare two things. When comparing windows, the two topmost document windows currently opened in Alpha will be compared, the topmost window being considered the old file.
The Compare submenu is dynamical: holding down the Alt key (⌥) displays two new menu items called Compare ↣ Windows Word By Word and Compare ↣ Selections Word By Word, which give you more fine-grained differences and ignore changes which amount to differences in line breaking.
The Compare ↣ Comparison Options… menu item displays a dialog in which you can specify some flags that modify the way the comparisons are executed. See the Comparison options section below.
The Compare ↣ Diff Prefs… menu item lets you set some preferences concerning the Diff Windows . They are described in the Diff Mode Help page.

Diff windows

When a diff has been executed, a Diff Window is opened and a new Diff menu is inserted in the menu bar.
If you are comparing two windows or two files, the Diff Window contains a list of diff codes that describe the differences found between the two objects. The document windows are positioned side by side over the Diff Window and navigation through the diff codes (using the Up and Down arrow keys) lets you visualize the corresponding lines in the documents. The syntax of diff codes is described in details in the Diff codes section below. If the Display Only Diff Codes preference is set, the Diff Window displays only the list of diff codes, otherwise it also displays the differing lines corresponding to each diff code: lines that the first file has are prefixed with "<" and lines that the second file has are prefixed with ">".
If you are comparing two folders, the Diff Window contains a list of lines describing which files differ in the folders, or which files are present only in one of them. Folders comparison may be recursive or not (see the Comparison options section below).
Navigation in the Diff Windows is described in details in the Diff Windows Navigation section of the Diff mode help.

Diff codes

The differences found between two windows, selections or files are displayed in the Diff Window and are symbolically represented by a diff code which is a string of the form: 
m1?,n1?[acd]m2?,n2?
The syntax of these diff codes (or markers) is described, through various examples, in the next paragraphs. Letter a stands for added, c stands for changed and d stands for deleted.
As a main principle, diff codes refer to line numbers starting with 1. A range of lines is specified as 3,6 to represent the four lines from 3 to 6. If a range consists of only one line it can also be specified by a single number.
A pair of diffing ranges can be specified for instance as 2,4c3,8 meaning that lines 2 to 4 in the left-hand file are different from lines 3 to 8 in the right-hand file (and of course it is understood that the surrounding lines match up, such that line 1 in the left-hand file is identified as matching line 2 in the right-hand file, and similarly line 5 matches line 9).
If some range of lines is found in file1 but not in file2, the file2 range is empty! In this case the convention is to indicate the corresponding gap between lines by indicating the number of the previous line. This is written, for instance, like 4,7d6. The d means that the range 4 to 7 has been deleted and that the corresponding gap is after line 6. In the opposite direction, this is indicated with an a, like in 3a3,7. It is crucial to observe that the right-hand number in a type 'a' or 'd' code is the number of a gap, not the number of a line. In particular, it could have the value 0, if the missing line is the first one. In other words, if a file has 9 lines, then they are numbered from 1 to 9, but the gaps between the lines are numbered from 0 to 9.

Comparison options

This section describes the various options that can be set using the Compare ↣ Comparison Options… menu item.
Compare Folders Recursively
When comparing folders, recursively compare all subfolders found.
Ignore Case
Ignore changes in case; consider uppercase and lowercase letters equivalent.
Ignore Blank Lines
Ignore changes that just insert or delete blank lines.
Ignore Space Changes
Ignore changes in amount of white space.
Ignore White Space
Ignore all white space when comparing lines.
Ignore Tab Expansion
Ignore changes due to tab expansion.
Treat All Files As Text
Treat all files as text and compare them line-by-line, even if they appear to be binary.

Examples

Some example files are available.
Click on this Compare Example hyperlink, which compares two versions of a .tcl file found in the Examples folder.
Click on this CompareWordByWord Example hyperlink which compares two texts word by word.

Note to developers

Alpha's diff'ing capacity is available through the [diffFiles] core command which may also be used directly in AlphaTcl packages.
There are many different formats used by diff tools to report the found differences. The diffFiles command produces its diff codes in the same format as the so-called "normal" format provided by the Unix diff command line tool. See the Diff codes section.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 1997-2020, Vince Darley and Contributors.
Contributors: Joachim Kock, Jon Guyer, Craig Barton Upright, Bernard Desgraupes.
All rights reserved.
The Compare package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL VINCE DARLEY OR THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.