Skip to content

Commit a5573e4

Browse files
LethjaLethja
committed
Initial adding of script unit test and documentation
1 parent b10f160 commit a5573e4

File tree

11 files changed

+200
-2
lines changed

11 files changed

+200
-2
lines changed

‎README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,14 @@ that are particularly useful on platforms that have no native equivalent.
55
Unfortunately, some scripts have been squashed
66
so they can all fit in the size limits of a floppy disk,
77
which can cause unintentional obfuscation of code.
8-
To rectify this, markdown files with the same name will document functions and
9-
variables.
8+
Unit tests have been created in these instances to make sure the script works
9+
as intended.
1010

1111
The scripts are split into the following folders:
1212

1313
| Folder Name | Description |
1414
|----------------|--------------------------------------------------------------------------------------------|
1515
| [core](./core) | Scripts that go in all distribution, namely included in the 160K floppy disk image |
16+
| [test](./test) | Unit tests for scripts that require them |
1617
| [util](./util) | Scripts that help with the build process of Lua for Watcom but aren't included on any disk |
1718
| [xtra](./xtra) | Extra scripts that are omitted from the 160K floppy disk image duo to space constants |

‎test/DIFF/DIFF.LUA‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../xtra/DIFF.LUA

‎test/DIFF/README.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# DIFF.LUA
2+
3+
## Overview
4+
This Lua script is a custom implementation of a **unified diff** utility.
5+
Its purpose is to compare one or more pairs of files,
6+
highlight their differences, and print them in a unified diff format,
7+
just like `git diff` or `diff -u`.
8+
9+
Unified diffs display added, removed, and a few unchanged lines, above and below
10+
to give contextual information that can then be used by a patching utility
11+
to ensure the patching process is correct.
12+
13+
## Usage Examples
14+
### Compare a file to another
15+
The script can compare a file to another as follows:
16+
```
17+
DIFF.LUA old.txt new.txt
18+
```
19+
This command compares `old1.txt` with `new1.txt`.
20+
### Compare multiple files to each other
21+
It might be useful to compare multiple files to their counterparts
22+
at the same time. The script can compare multiple sets files as follows:
23+
```
24+
DIFF.LUA old1.txt new1.txt old2.txt new2.txt old3.txt new3.txt
25+
```
26+
This command compares `old1.txt` with `new1.txt`,
27+
`old2.txt` with `new2.txt` and `old3.txt` with `new3.txt`.
28+
This can continue indefinitely.
29+
30+
31+
## How It Works
32+
The script performs the following steps:
33+
1. **Input Validation**:
34+
- There should be at least two arguments representing a valid file.
35+
- Each two arguments will be treated as another set of files to compare.
36+
The number of arguments must always be an even number.
37+
- If the provided input is invalid,
38+
the script outputs usage instructions and exits.
39+
- If any file can't be opened for any reason,
40+
the script will print an error and exit on the spot.
41+
42+
2. **File Comparison**:
43+
- The function `diff_u` performs the actual comparison:
44+
- It reads two files line by line.
45+
- It tracks which lines are added, removed,
46+
or unchanged between the two files using the Myers diff algorithm
47+
- It groups changes in "hunks,"
48+
which are logical sections of differences,
49+
and formats these differences in the unified diff style.
50+
- It adds context lines around hunks to provide additional verification.
51+
52+
3. **Unified Diff Output**:
53+
- The script outputs differences using a standardized format:
54+
- Lines starting with a space (` `) are unchanged context lines.
55+
- Lines starting with a minus sign (`-`) are present only in the "old file" (removed lines).
56+
- Lines starting with a plus sign (`+`) are present only in the "new file" (added lines).
57+
- Each hunk starts with a header
58+
that shows the affected line numbers in both files,
59+
e.g., `@@ -start,count +start,count @@`.
60+
- If the old and new files are identical, nothing will be printed
61+
62+
## Global Variables
63+
64+
| Variable | Description |
65+
|----------|------------------------------------------------------------------------------------------------------------------------------------------------|
66+
| `CL` | **C**ontext **L**ines to print above and below a hunk. Defaults to `3`, can be to something else with the `DIFF_CONTEXT` environment variable. |
67+
68+
## Functions
69+
70+
| Function | Parameters | Description |
71+
|----------|-------------------------------------------------|-----------------------------------------------------------------------------|
72+
| `diff_u` | **f**ile**n**ame**1**<br/>**f**ile**n**ame**2** | Prints differences between the two files in to stdout. |
73+
| `fp` | | **F**lushes **p**re-context lines into the buffer when changes are detected |
74+
| `fh` | | **F**lushes a complete **h**unk of changes into the buffer |
75+
| `fb` | | **F**lush (print) and clear the **b**uffer |
76+
| `di` | | **D**iagonally **i**terate (lines that match in both files) |
77+
| `ri` | | **Ri**ght iterate (for a line only present in the old file) |
78+
| `dn` | | **D**ow**n** Iterate (for a line only present in the new file) |

‎test/FATSTAT/FATSTAT.LUA‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../util/FATSTAT.LUA

‎test/FATSTAT/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# FATSTAT.LUA
2+
3+
This Lua script reads and reports on the sector usage
4+
on FAT 12/16 formatted floppy disk images.
5+
Additionally, it has an optional function to zero out free clusters.
6+
This script is used in continuous integration of Lua for Watcom
7+
to ensure IMA floppy disk images
8+
containing the same files
9+
copied in the same order
10+
with the same metadata
11+
always have the same checksum.
12+
This might be necessary because copy commands may use free sectors like a cache.
13+
14+
## Documentation
15+
16+
This script has been squashed to save on disk space.
17+
The documentation for the functions are below.
18+
19+
### Functions
20+
21+
| **Function** | **Description** | **Output** |
22+
|-----------------|---------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
23+
| `R16`</br>`R32` | **R**ead **16**-bit (`R16`) or **32**-bit (`R32`) integers from a data string at a specified offset. | Parsed values (e.g., total sectors). |
24+
| `F12`</br>`F16` | Decodes the FAT table for **F**AT**12** (`F12`) or **F**AT**16** (`F16`). | Returns a table representing the FAT. |
25+
| `FD` | **D**etermines the **F**AT type based on the total cluster count. FAT12 if <4085 clusters, FAT16 if <65525. | FAT type and total cluster count. |
26+
| `CC` | Follows the FAT **c**luster **c**hain to identify which clusters are allocated to a file. | A list of clusters allocated to the file. |
27+
| `FR` | **F**ormats a list of clusters into a readable **r**ange string (e.g., `<2-4>`, `<5>`). | String representation of cluster ranges. |
28+
| `DE` | Reads **d**irectory **e**ntries (files) from the root directory and retrieves their cluster allocation information. | Outputs file names and cluster ranges. |
29+
| `FC` | Identifies **f**ree **c**lusters and optionally writes zeros to them if the `-z` flag is used. | Ranges of free clusters. |

‎test/MD5SUM/MD5SUM.LUA‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../xtra/MD5SUM.LUA

‎test/MD5SUM/test.sh‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/usr/bin/env sh
2+
3+
INTERP=${INTERP:-lua}
4+
TEST="MD5SUM"
5+
SCRIPT="MD5SUM.LUA"
6+
7+
GNU=$(md5sum $SCRIPT)
8+
LUA=$($INTERP $SCRIPT $SCRIPT)
9+
10+
if [ "$GNU" = "$LUA" ]; then
11+
echo "$TEST PASS"
12+
exit 0
13+
else
14+
echo "$TEST FAIL"
15+
exit 1
16+
fi

‎test/PE95TIME/PE95TIME.LUA‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../util/PE95TIME.LUA

‎test/PE95TIME/README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# PE95TIME.LUA
2+
3+
This Lua script modifies timestamps
4+
in a Portable Executable (PE) format EXE file
5+
to align them with the release date of Windows 95.
6+
The goal is to ensure reproducible builds for checksum verification purposes.
7+
This script is used in continuous integration of LUA for Watcom
8+
to ensure LUANT.EXE built from the same source code
9+
always has the same checksum.
10+
11+
## Documentation
12+
13+
This script has been squashed to save on disk space.
14+
The documentation for the scripts variables and functions are below.
15+
16+
### **Globals**
17+
| Global Variable | Description |
18+
|-------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
19+
| The `F`ile | The open PE exe file in the script. The rest of this documentation will refer to this variable as "the file" as the script never has more than one file open at any time and is always assigned to this value. |
20+
| Little-endian `I`nteger | A constant used in Lua's `string.pack` and `string.unpack` functions (little-endian, 4-byte integers). Referring to `I` takes fewer bytes than typing `"<I4"` every time. |
21+
| Header `J`ump | Set to the offset of a PE header in the file then reused and later the offset of ".rsrc" |
22+
| `K` | The size of the table being jumped to |
23+
| INT32 MA`X` | A constant used for bitwise operations. Represents the maximum 32-bit signed integer. Referring to `X` takes fewer bytes than typing `"0x80000000"` every time. |
24+
| `V`alue | The timestamp representing the Windows 95 release date in Unix epoch. Referring to `V` takes fewer bytes than typing `809222400` every time. |
25+
| `H`elp String | A string containing the help message. |
26+
27+
---
28+
29+
### **Functions**
30+
31+
| Function | Parameters | Description |
32+
|--------------------|------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
33+
| Seek `C`urrent | byte position (optional) | Move the file forward or backward from its current point by the specified amount of bytes. If byte position is not specified then the current position will be returned. |
34+
| `S`et Point | byte position | Set the file pointer to the exact byte location in the file. |
35+
| `R`ead Short/Int | 2 for 16-bit or 4 for 32-bit | Read a 16/32-bit value from the current point of the file. the point is moved by the amount of bytes read. The returned value is a integer representation of the requested data. |
36+
| `W`rite Int | 32-bit, byte position | Overwrite 32-bits of data in the file at the exact byte location in the file. |
37+
| `P`arse Executable | | Verify that this is a binary executable. If it can't be verified nil is returned and the caller should close the file. |
38+
| PE Header `O`ffset | | Parse through the file setting `J` to ".rsrc" section |
39+
| `B` | byte position, size | Find and set timestamp headers in 'VS_VERSION_INFO' |
40+
| `A` | byte position, depth, isSub | Modifies DateTimeStamp to `V` as it iterates over PE Headers. Calls `B()` if 'VS_VERSION_INFO' resource is found |
41+
42+
### Execution Pipeline
43+
44+
1. Ensures at least one argument is provided.
45+
- If no arguments are provided, help is printed and the program exits.
46+
2. For each file listen as an argument:
47+
1. Opens it in read/write mode (`r+b`) as "the file".
48+
- If "the file" doesn't exist or cannot be opened for writing, the program exits with an error on the spot.
49+
2. Calls `P()` to locate the PE header and `O()` to locate the `.rsrc` section.
50+
- If the MZ signature, PE header or .rsrc section cannot be found, the program exits with an error on the spot.
51+
3. Calls `A()` to process the `.rsrc` directory structure and update version information timestamps.
52+
1. `B()` is called if 'VS_VERSION_INFO' is discovered during interation.
53+
4. Closes the file and reports success.

‎test/S256SUM/S256SUM.LUA‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../core/S256SUM.LUA

0 commit comments

Comments
 (0)