This file is a help file for DiffBOA, a background only application to make diff's between files or folders. It demonstrates how to use it from the AppleScript editor or any external application. It documents version 2.0 of DiffBOA.

Introduction

DiffBOA is a port to the Macintosh of the GNU diff utility. It lets you compare and find differences between two files. Its output can be written in many different standardized formats and it has a lot of configuration options. DiffBOA is built for Mac OS X. It is a background only application (BOA). It has no user interface, yet it is not a command line tool: it is designed to be driven via AppleEvents. It can thus be invoked by any application: in particular, AppleScript Editor will allow you to use it in scripts written in the AppleScript language. The Alpha text editor is an application using the service of DiffBOA to make diffs between files.

Line endings

Macintosh, Unix and Windows files have different kinds of line endings: Macintosh files have cr line endings, Unix files have lf line endings and Windows files have crlf line endings. A nice feature of DiffBOA, which is not found in the original GNU diff, is that it can compare any of these files together, no matter what kind of line endings they are using. By default, DiffBOA is able to guess the type of the files, but this can also be specified explicitly if necessary.

Syntax of DiffBOA

DiffBOA is AppleEvent driven: you can either invoke it from an AppleScript script using its terminology or send it an AppleEvent, directly or through any programmatic interface. The next two sections explain the syntax to do this: the first one concerns the AppleScript syntax, the second one concerns the AEgizmo syntax used by the Alpha text editors (using the Tcl language).
The terminology to use DiffBOA with AppleScript can be found by opening its dictionary from the AppleScript Editor.

Using DiffBOA from AppleScript Editor

This section explains how to communicate with DiffBOA using scripts written in the AppleScript language. In all these examples, it is assumed that we are comparing two files named lao and zi respectively. These files are eventually provided in the DiffBOA distribution. For the sake of simplicity, we store them in variables also named lao and zi. This can be done like this in AppleScript (adjust the paths to the actual location of the files on your system):

set lao to "HD:Users:mylogin:Documents:lao" as alias
set zi to "HD:Users:mylogin:Documents:zi" as alias

Example 1

The basic command to make a diff between the files lao and zi is

tell application "DiffBOA"
    Diff old lao new zi
end tell

The two terms old and new are required parameters of the Diff command. Note: the Diff command must be issued in a tell block as in the previous example. To make this document easier to read, the tell block will not be repeated in all the following examples of this section, but it is required for the AppleEvents manager to identify the target of the event.

Example 2

One can specify a particular output format using the in format optional argument. For instance:

Diff old lao new zi in format 3

will produce the result in unified format. Nine formats are currently available: see the Output formats table below.

Example 3

Many boolean options are available to customize the diff process. One can ask to ignore case differences, or white spaces, or blank lines while performing the diff. For instance:

Diff old lao new zi with ignore case and ignore all space

All the options can be found in the Diff parameters table below.

Example 4

DiffBOA would normally guess automatically what type of line endings is used in any of the text files it compares. In case of ambiguity, you can specify the line endings explicitely using the old endings and new endings arguments. For instance:

Diff old lao new zi old endings "cr" new endings "lf"

If the line endings are identical for both files, use the both endings argument, like this:

Diff old lao new zi both endings "crlf"

The values for specifying the different line endings are shown in the Line endings table below.

Example 5

In context (=2) and unified (=3) formats, the first two lines of the output contain the complete path of the files followed by their modification date. This can be modified using the label1 and label2 arguments, corresponding to the old and the new file respectively. For instance:

Diff old lao new zi in format 3 label1 "yeoldefile" label2 "yenieuwfile"

Example 6

The ifdef output format (=5) contains all the lines of both files. Lines common to both files are output just once; the differing parts are separated by C preprocessor directives (#ifdef, #ifndef, etc.). To specify the name of the preprocessor macro used in the directives, specify the ifdef constant argument. For instance:

Diff old lao new zi in format 5 ifdef constant "MY_CONSTANT"

Example 7

The ifdef output is very flexible and can be entirely customized. The new line, old line, unchanged line arguments let you modify the format of each kind of line in the output. For instance, to have old lines start with <<<, new lines start with >>> and common lines start with ---, one can write:

Diff old lao new zi in format 5 ifdef constant "MY_CONSTANT"  ¬
new line ">>> %l\n" old line "<<< %l\n" unchanged line "--- %l\n"

The ¬ symbol is AppleScript's line continuation symbol which allows a statement to span across multiple lines. All three line formats can be changed simultaneously using the line format parameter. For instance, to have all lines start with -->:

Diff old lao new zi in format 5 ifdef constant "MY_CONSTANT" line format "--> %l\n"

The groups of lines can also be customized with the old group, new group, unchanged group, changed group arguments. For instance to change the preprocessor macros mentionned above and replace them by XML like tags, one can write:

Diff old lao new zi in format 5 ifdef constant "MY_CONSTANT" ¬
	 old group "<old>%<</old>\n" new group "<new>%></new>\n"  ¬
	 unchanged group "<common/>\n" ¬
	 changed group "<differ><old>%<</old><new>%></new></differ>\n"

There are more advanced possibilities, letting you specify line numbers, file names etc. See the diff documentation to learn more about this.

Example 8

DiffBOA has an option (not found in the original diff tool) which will output only the locations where differences are found but without writing any line of the text. The format used to describe the differences is the same as in unified format. This option is named short unified and can be very useful for text editors which already have both versions of the files and only need to know where they differ. Here is an example:

Diff old lao new zi with short unified

The output could be something like this:

@@ -1,2 +0,0 @@
@@ -4 +2,2 @@
@@ -11,0 +11,3 @@

Using DiffBOA from Alpha

This section explains how to communicate with DiffBOA from the Alpha text editor. The Alpha text editors embed a Tcl interpreter and AppleEvents are sent using the tclAE::send command. The examples below demonstrate the use of this command which can be executed from the Tcl shell in Alpha or from any Tcl script interpreted by Alpha. The tclAE::send command is defined in the tclAE extension, so it is also possible to issue the following instructions from the tclsh tool on the command line of a Terminal window after loading this extension. One must first launch DiffBOA. This is achieved like this in Alpha:

switchTo -p /path/to/DiffBOA

For instance, the path to DiffBOA inside Alpha's bundle is Alpha.app/Contents/Resources/Libraries/Extras/DiffBOA.app.
After each execution, DiffBOA will automatically quit. You have to launch it each time you make a diff. If you need to quit DiffBOA manually, use one of the following instructions:

tclAE::send 'DifB' aevt quit

sendQuitEvent bund("net.alphacocoa.diffboa")

To experiment, we shall be using the same two files, named lao and zi, as in the previous section. Their path will be stored in variables named f1 and f2 respectively. For instance:

set f1 [file join Users mylogin Documents lao]
set f2 [file join Users mylogin Documents zi]

Example 1

The basic instruction to make the diff is:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                                Newf [tclAE::build::alis $f2]

The Oldf and Newf parameters are the only required parameters for the AppleEvent. The others, explained in the examples below, are optional. See the Diff parameters table for an exhaustive list.

Example 2

One can specify a particular output format using the Frmt optional parameter. For instance:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                      Newf [tclAE::build::alis $f2] \
                      Frmt 3

will produce the result in unified format. Nine formats are currently available: see the Output formats table below. By default, DiffBOA uses the normal output format.

Example 3

The files can have different types of line endings. They are specified with the Eol1 and Eol2 parameters. Here is an example:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                                Newf [tclAE::build::alis $f2] \
                                Eol1 1 Eol2 2

Here we specify that the old file is a Macintosh file and the new file is a Unix file. The values for specifying the different line endings are shown in the Line endings table below. One can also specify both line endings at a time with the Eols parameter, like this:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                                Newf [tclAE::build::alis $f2] \
                                Eols 2

This instruction means that both files are Windows files. Normally, line endings do not have to be specified: DiffBOA is able to guess the correct type. Use these parameters only in case of ambiguity.

Example 4

One can do a case insensitive diff with the Igca (ignore case) parameter. For instance:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                                Newf [tclAE::build::alis $f2] \
                                Igca 1

You can do a diff ignoring the space differences. There are several parameters for this: ((lu ((li Igta corresponds to the --ignore-tab-expansion option ((li Igsp corresponds to the --ignore-space-change option ((li Igal corresponds to the --ignore-all-space option lu)) They are in increasing order of precedence, which means that Igsp implies Igta, and Igal implies both Igsp and Igta. For instance:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                                Newf [tclAE::build::alis $f2] \
                                Igsp 1

Similarly, in order to ignore blank lines, use the Igbl parameter (corresponding to the --ignore-blank-lines option). For instance:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                                Newf [tclAE::build::alis $f2] \
                                Igbl 1 Igsp 1

Example 5

In the context and unified formats, you can specify the number of lines of context you want to display. Use the Cntx parameter (the default value is 3 and it can't be less than 3):

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                                Newf [tclAE::build::alis $f2] \
                                Frmt 3 Cntx 4

The Lab1 and Lab2 parameters let you specify the first two lines of the diff output in context and unified formats. For instance:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                                Newf [tclAE::build::alis $f2] \
                                Frmt 2 \
                                Lab1 [tclAE::build::TEXT "yeoldefile"] \
                                Lab2 [tclAE::build::TEXT "yenieuwfile"]

Example 6

In the ifdef format, you must specify the constant to use in the #ifdef, #ifndef, etc. statements. This is done with the Ifct parameter. For instance:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
                                Newf [tclAE::build::alis $f2] \
                                Frmt 5 \
                                Ifct [tclAE::build::TEXT "MY_CONSTANT"]

Here are a few more elaborate examples which implement the same instructions already shown in the Using DiffBOA from AppleScript Editor section. To modify the line formats individually:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
								Newf [tclAE::build::alis $f2] \
								Frmt 5 \
								Ifct [tclAE::build::TEXT "MY_CONSTANT"] \
								Olin [tclAE::build::TEXT "<<< %l\n"] \
								Nlin [tclAE::build::TEXT ">>> %l\n"] \
								Ulin [tclAE::build::TEXT "--- %l\n"]

or to modify all three of them identically:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
								Newf [tclAE::build::alis $f2] \
								Frmt 5 \
								Ifct [tclAE::build::TEXT "MY_CONSTANT"] \
								Lfmt [tclAE::build::TEXT "--> %l\n"]

To modify the layout of the groups of lines:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
								Newf [tclAE::build::alis $f2] \
								Frmt 5 \
								Ifct [tclAE::build::TEXT "MY_CONSTANT"] \
								Ogrp [tclAE::build::TEXT "<old>%<</old>\n"] \
								Ngrp [tclAE::build::TEXT "<new>%></new>\n"] \
								Ugrp [tclAE::build::TEXT "<common/>\n"] \
								Cgrp [tclAE::build::TEXT "<differ><old>%<</old><new>%></new></differ>\n"]

Example 7

In order to get only the locations where differences occur, without writing any line of the text, use the short unified feature which is specified with the Shrt boolean parameter. Here is an example:

tclAE::send -r 'DifB' Diff DoDf Oldf [tclAE::build::alis $f1] \
								Newf [tclAE::build::alis $f2] \
								Shrt 1

Example 8

Incidentally, you can also get DiffBOA's version number like this:

tclAE::build::resultData 'DifB' Diff Vers

Reference

Diff event parameters

The AppleEvent to run a diff has class 'Diff' and ID 'Diff' too. Two parameters are required: the specification (as an alias) of the two files to compare. All the other parameters are optional. It implements the AppleScript Diff command. The following table contains the list all the available parameters. When applicable, the last column indicates which option of the original diff tool is implemented by a parameter.

Terminology	Keyword	Type	Status	Description
old	'Oldf'	'alis'	required	the old file
new	'Newf'	'alis'	required	the new file
in format	'Frmt'	'long'	optional	the output format (see Output formats table)
context lines	'Cntx'	'long'	optional	the number of context lines (in context and unified formats)
column width	'Colw'	'long'	optional	the column width (in side-by-side format)
old endings	'Eol1'	'long'	optional	line endings for old file (see Line endings table)
new endings	'Eol2'	'long'	optional	line endings for new file (see Line endings table)
both endings	'Eols'	'long'	optional	line endings for both files (see Line endings table)
ignore case	'Igca'	'bool'	optional	the --ignore-case option
ignore blank lines	'Igbl'	'bool'	optional	the --ignore-blank-lines option
ignore space change	'Igsp'	'bool'	optional	the --ignore-space-change option
ignore all space	'Igal'	'bool'	optional	the --ignore-all-space option
expand tabs	'Xtab'	'bool'	optional	the --expand-tabs option
initial tab	'Itab'	'bool'	optional	the --initial-tab option
ignore tab expansion	'Igta'	'bool'	optional	the --ignore-tab-expansion option
recursive	'Recu'	'bool'	optional	the --recursive option
report identical files	'Iden'	'bool'	optional	the --report-identical-files option
new-file	'Nfil'	'bool'	optional	the --new-file option
unidir new file	'Unid'	'bool'	optional	the --unidir-new-file option
treat as text	'Text'	'bool'	optional	the --text option: treat as text. Default is 1.
show c function	'Cfnt'	'bool'	optional	the --show-c-function option
left column	'Lcol'	'bool'	optional	the --left-column option
suppress common	'Scom'	'bool'	optional	the --suppress-common-lines option
short unified	'Shrt'	'bool'	optional	report only differing line numbers in unified format
minimal	'Mini'	'bool'	optional	the --minimal option: try hard to find a smaller set of changes
speed large files	'Splf'	'bool'	optional	the --speed-large-files option: assume large files and many scattered small changes
ignore file name case	'Igfc'	'bool'	optional	the --ignore-file-name-case option
ifdef constant	'Ifct'	'TEXT'	optional	the constant for ifdef format
exclude pattern	'Xpat'	'TEXT'	optional	the --exclude-pattern option
ignore match lines	'Igml'	'TEXT'	optional	the --ign-match-lines option
label1	'Lab1'	'TEXT'	optional	the --label option for the old file
label2	'Lab2'	'TEXT'	optional	the --label option for the new file
unchanged group	'Ugrp'	'TEXT'	optional	the --unchanged-group-format option
old group	'Ogrp'	'TEXT'	optional	the --old-group-format option
new group	'Ngrp'	'TEXT'	optional	the --new-group-format option
changed group	'Cgrp'	'TEXT'	optional	the --changed-group-format option
unchanged line	'Ulin'	'TEXT'	optional	the --unchanged-line-format option
old line	'Olin'	'TEXT'	optional	the --old-line-format option
new line	'Nlin'	'TEXT'	optional	the --new-line-format option
line format	'Lfrm'	'TEXT'	optional	the --line-format option to format all input lines

Line endings

The various kinds of line endings are shown in the next table:

Name	Value	Description
Undefined	0	Unspecified: let DiffBOA guess
Mac	1	cr (0x0d)
Unix	2	lf (0x0a)
Windows	3	crlf (0x0d0a)

Output formats

The various output formats are shown in the next table:

Name	Value	Description
Normal	1	normal output format
Context	2	context output format
Unified	3	GNU unified output format
SideBySide	4	Side-By-Side output format
Ifdef	5	If-Then-Else output format
Brief	6	brief output format
Ed	7	Ed script output format
ForwardEd	8	ForwardEd output format
RCS	9	RCS output format

Last updated 2018-12-21 09:14:30