Basic File Differentiator
by Lewis G. Kirby

This application finds the differences between two Basic programs. It is not a simple file comparator; it actually shows which lines have been deleted from, inserted into, or simply changed in the first program in order to produce the second. Running the application displays a dialogue box into which the user should drag the two program files; the resulting difference file may then be saved.

The difference file is actually a Command (*Exec) file which will, if executed, carry out the following: (1) LOAD the first program; (2) delete lines which were in the first but not in the second; (3) insert lines which were either not in the first or were changed; (4) SAVE the resulting changed program using the filename of the second program.

The application makes use of the RISC User WimpLib parts 1 and 2. The system variable WimpLib$Dir must be set to point to the current location of the WimpLib. If this is within the !BasDiff application directory (as on this disc), then BasDiff's !Run file must include the line:
  
  Set WimpLib$Dir <Obey$Dir>

There are three distinct uses for the application:

1. Determine whether and where a program has differed from one version to the next. For example, you may have altered a program and found it no longer works, and you want to know exactly what has been changed from the old version to the new (both versions must still exist!). In this case the difference file should not be executed, but simply examined.

2. Provide updates for users of your code. For example a program published in RISC User may be updated by giving new sections of code with which readers may amend their existing program. In this case the difference file could be included on a magazine disc, and users would execute it to produce the upgraded program from the original.

3. Maintain a series of Delta files for your programs. If you are involved in a software project in which all changes to code must be monitored, then only the original version needs to be kept, along with a set of difference files which indicate how to progress from one version to another. In other words, if you need to keep several versions of a program concurrently then by using BasDiff you only need to keep one original version plus the set of Difference files. You would normally also maintain the most recent version.

There are two options available from the dialogue box: Ignore line numbers and Ignore leading spaces.

If the first of these is selected, the application will consider two lines to be different only if the program content of the lines differs (i.e. excluding the line number); if the option is off then both line number and program content are taken into account. If line numbers are referenced in the program (i.e. GOTO, GOSUB, RESTORE etc.) then this option should be turned off, otherwise an error will be generated. 

The second option, to ignore leading spaces, ensures that programs are not differentiated simply because of differing indents.

To use BasDiff, first drag the original program into the dialogue box, followed by the second, changed version, as prompted at the foot of the window. When the differences have been determined, a "Save as:" prompt appears, allowing you to save the difference file in the usual way, either by dragging the icon to a directory viewer or by clicking on OK.

The second (changed) file may now be deleted if required. It can be reproduced simply by double clicking on the difference file icon. Note, however, that the difference file uses absolute (i.e. full) pathnames and so the changed file will only be reproduced if the original file is where it is expected to be; you can edit the difference file if it is not. 

The amount of time the application takes to determine the differences between two files depends on the lengths of the programs and how different they are. The size of the difference file also depends on these. Obviously if the two files to be compared are completely different then the application will spend a long time discovering that they are different, and the difference file will consist almost entirely of statements from the second file.

The difference file consists of comments (preceded by "*|") and Basic commands and statements. The comments include the names of the two files and the date the differencing was done.

Possible errors
---------------

Too many lines in <filename> - there are too many lines in the file; see below for how to change the program to accommodate this. 

Buffer for <filename> full - the internal buffer has overflowed when reading the file; see below for how to change the program to accommodate this.

Line number references not allowed - if option "Ignore Line Numbers" is "on" then neither program is allowed to contain references to line numbers (e.g. no GOTO, GOSUB, etc.).


The program contains two variables which control the size of program that can be handled: buffer size bufSize% (currently set to 400*256=102400=10K) and number of lines maxLines% (currently set to 1000). This is because lines are usually a lot less than the maximum allowed length of 256. If all program lines were 256 bytes long then the buffer size would allow only 400 lines; as it is, double that number have been allowed for. The user is free to change either of these variables since overflow in both is checked; however changing bufSize% would probably mean changing the 320K WimpSlot setting in the !Run file.

When the application finds two lines which are different, it looks ahead to see whether a copy of the line actually occurs later in the other file. The size of this look-ahead can have a large effect on performance; obviously if the files are very different and the look-ahead is large then finding the differences will take a long time. Usually, however, the files are not very different and so the look-ahead could be set to a small value. Ideally the look-ahead should be to the end of the file (i.e. as large as possible) but it is set at maxLines%DIV4+10. This means that for small files the look-ahead is to the end of the file but for larger files it is less, until for the maximum size of file the look-ahead is about a quarter through the file. The value is set as "ahead%" in PROCinit and may be changed, but setting it to low values (less than 20) is not recommended.

The default choice for both the options is "on". The user may change this by altering the values for numIgnore% and/or spcIgnore%; the choice "on" corresponds to the value TRUE.
