SYNTAX

Compare file1 [file2] [-b] [-c col1-col2[,col1-col2]] [-d depth]
[-e context] [-g groupingFactor] [-h lineWidth] [-l] [-m] [-n] [-p]
[-s] [-selection set | next] [-t] [-v] [-w max] [-x]

DESCRIPTION

The Compare tool compares the lines of two text files and writes their differences to standard output. This tool describes each difference in a message containing the type of difference (that is, either nonmatching or extra lines), the MPW Shell editor commands that select the lines in question, and the differing lines.

To generate this output, Compare performs more than a simple one-to-one comparison. Whenever it finds a difference, Compare stores the lines while it searches each file alternately for another match to resynchronize. A file is considered synchronized when a certain number of lines (called the grouping factor) match exactly. When these matching lines are found, Compare writes the previous difference (for example, mismatched lines at line 120) to standard output.

The grouping factor depends solely on the number of mismatched or extra lines and is calculated according to the formula

G = Trunc((2.0 * Log₁₀(M)) + 2.0)

where G represents the grouping factor and M represents the number of mismatched or extra lines. Using this formula, Compare requires more lines to be the same after larger mismatches. For example, if the first file (file1) contains a 100-line procedure not found in the second (file2), Compare requires a grouping factor of 6. On the other hand, if the procedure contains only 8 lines, the grouping factor drops down to 3.

For your reference, the table below shows the grouping factor G as a function of the number of mismatched or extra lines M.

Although the grouping factor G is dynamic by default, you can fix it as a static number by using the static option (-s) with -g. If you omit -s, the grouping factor remains dynamic and -g allows you to set the minimum grouping factor.

A static G may be desirable under some circumstances, but be aware that it can resynchronize files at undesirable points, especially if G is too small. It is recommended that you use the default first; if the results are not satisfactory, try a higher minimum value of dynamic G (such as 3 or 4). If that is still unsatisfactory, try a static G.

With either option, there is a limit on how far out of synchronization the two files can get before they're no longer worth comparing. For a dynamic G, the limit on the number of mismatched lines is 1000, but you can choose a lower limit with the depth option (-d). For the static G option, typical values for G are 1 to 5 with a maximum number of mismatched lines between 10 and 50. (The default limit is 25.)

INPUT

None, unless you omit the file2 parameter, in which case file1 is compared to standard input.

OUTPUT

Standard output. Compare first writes the names of both files to standard output (file1 and either file2 or standard input). It then writes all differences between the two files as messages. These messages include the types of differences, the MPW Shell editor commands that you can use to select the lines, and the differing lines themselves.

Depending on the difference, Compare produces a message that takes one of the following forms:

Nonmatching lines (Shell editor commands)
  …displays lines from both files…

Extra lines in 1st before <line> in 2nd (editor commands)
  …displays lines from file1…

Extra lines in 2nd before <line> in 1st (editor commands)
  …displays lines from file2…

Extra lines in 1st file (editor commands)
  …displays lines from file1…

Extra lines in 2nd file (editor commands)
  …displays lines from file2…

The MPW Shell editor commands consist of File and Line (Line is provided in the MPW Scripts folder) commands to select the mismatched lines. If there are extra lines in one file and not the other, the selection for the missing lines is generated as an insertion point at the point where the lines are missing.

Several options alter the message form slightly. If you use the -e option, you can see the context in which mismatched or extra lines appear. In this case, you specify a certain number of context lines to precede and succeed the lines in question. If you request -m, on the other hand, Compare suppresses the differing lines altogether, including only the type of difference and the MPW Shell editor commands. See the -h and -v options for more formatting options.

If Compare reaches an end-of-file or the maximum number of mismatched or extra lines during resynchronization, one of the following messages also appears:

*** Nothing seems to match ***

*** EOF on both files ***

*** EOF on file 1 ***

*** EOF on file 2 ***

If the files are in synchronization and both reach their end-of-file at the same time, the following message appears if any mismatches occurred:

*** EOF on both files at the same time ***

If the files match, the following message is displayed:

*** Files match ***

STATUS

Compare can return the following status codes:

PARAMETERS

file1

Specifies the text file or selection in a file to be compared to file2.

file2

Specifies the text file to be compared to file1. If you omit this parameter, file1 is compared to standard input.

OPTIONS

-b

Treats several blanks (spaces or tabs) as a single space and ignores trailing blanks.

-c col1-col2[,col1-col2]

Compares only the columns col1 to col2 of each file. If you omit the second column range, the first range applies to both files; otherwise, the first range applies to file1, and the second range applies to file2.

If you omit col1, Compare assumes 1. If you omit col2, Compare assumes 255.

Note
To use -c, tabs must be expanded. The tab setting is determined from the file's tab value. See also -x for more information about tab expansion. •

-d depth

Sets the maximum number of mismatched or extra lines (depth)--that is, how far out of synchronization the files can get before they're no longer worth comparing. The value of depth is an integer value from 1 to 1000. The default is 1000 for dynamic grouping G, and 25 for static (-s) grouping G.

-e context

Displays up to context number of lines before and after the mismatched or extra lines. The Compare tool allows values of 1 to 100; however, context lines are shown only if they are equal in both files, so fewer than the specified number of lines may be shown.

Note that Compare ignores this option if you also specify -m.

-g groupingFactor

Specifies the grouping factor, G. For dynamic grouping, -g specifies the minimum grouping factor, that is, the minimum number of lines that must match for the two files to be considered resynchronized. This value must be at least 2, which is the default.

If you also use -s, this option specifies a fixed grouping factor. In this case, Compare allows values from 1 through 1000 with a default of 3.

-h lineWidth

Displays mismatches in a horizontal format in a line of lineWidth characters, where lineWidth can be any number from 70 to 255. This causes Compare to display only a portion of each nonmatching line
side by side.

-l

Ignores case differences by converting all lines to lowercase before comparing them. Normally Compare is case sensitive.

-m

Suppresses the display of mismatched and extra lines. Normally Compare displays the mismatched and extra lines along with the type of difference and the MPW Shell editor commands.

Compare ignores this option if you also specify -h.

-n

Does not write any messages to standard output if both files match.

-p

Writes progress information for Compare, including its version number, to diagnostic output.

-s

Specifies a static, or fixed, grouping factor to be set with -g. If you do not specify this option, the grouping factor G is dynamic by default.

-selection set | next

Controls the selections. This option is only used by the CompareFiles script.

set

Set the selections to highlight the first mismatch.

next

Starting with the selections created by -selection set, move the selections down in the windows to the next mismatch. Position the Shell windows so that 10 lines preceed each selection.

-t

Ignores trailing blanks (spaces or tabs). This is a subset of the -b option.

-v

Displays differences between two files in a format that allows output lines to be cut and pasted into a source file. That is, Compare suppresses the line number that normally precedes mismatched or extra lines. For example,

#This line does nothing

instead of

120 #This line does nothing

-w max

Set the maximum input line length to max. The default is 255. The greatest permissible value for max is 1024.

-x

Suppresses tab expansion. Tabs are expanded into spaces except when you use -b or -x. To expand tabs, Compare determines the tab value from each file's tab setting, which is stored as a resource; if there is no tab setting, Compare assumes 4 spaces per tab.

Caution
This option can cause lines to be displayed incorrectly in output messages if the files contain tabs. Also, do not use -c with -x because -c depends on the columns being displayed with tabs expanded. •

Note
All comparison criteria--column range (-c), blanks compression (-b), and case conversion (-l )--affect the way Compare displays lines in the output message. Lines appear in the form in which they are compared, which can be different from their original form due to the effect of these options. •

EXAMPLES

In the following example, a comment was added to Memory.p and the file was saved as Memory.p.revision. To find the comment, the command line

Compare Memory.p Memory.p.revision

is executed, producing the following output:

File #1: Memory.p

File #2: Memory.p.revision

Extra lines in 2nd before 120 in 1st (File "Memory.p"; Line ∆120; File "Memory.p.revision"; Line 120)

120 {This line does nothing}

*** EOF on both files at the same time ***

When executed, the MPW Shell editor commands

File "Memory.p"; Line ∆120; File "Memory.p.revision"; Line 120

select the extra line in Memory.p.revision.

The following command line compares the selected portions of the two windows, File.old and File.new, and writes out the results:

Compare File.old.§ File.new.§

LIMITATIONS

The maximum number of lines that can be processed is 65535 (any additional lines exceeding this limit are not reported).

SEE ALSO

CompareFiles

Equal