# hrust — Hrust 2 packing in Midnight Commander
Version 1.0.
A plugin for [Midnight Commander](https://midnight-commander.org/) (mc): it packs and unpacks ZX Spectrum files in the
Hrust 2 format (hr2), the one Quick Commander (QC) uses. The user menu (F2) gets the entries "Hrust: pack", "Hrust: pack
(oh2c)" and "Hrust: unpack", and F3 on a packed file shows it unpacked. The program `hrust` is a single Python 3 file
with no dependencies. It packs byte for byte as QC 3.11's `h` command did, or, with `-o`, as oh2c, the optimal packer
of the format, does; it unpacks as QC's depacker does. It needs mc 4.8 or later and works on Linux, macOS and BSD.
```
F2 the user menu
u Hrust: pack game.C -> game.p_C (as QC 3.11's h)
O Hrust: pack (oh2c) game.C -> game.p_C (the shortest block)
N Hrust: unpack game.p_C -> game.C
F3 on game.p_C or pic.hr2 the unpacked bytes (hex)
```
hr2 is a plain packed block: a header, then the packed data, and no depacker. It is unpacked by a program that has a
Hrust 2 depacker, such as QC (its `U` command and its viewers) or your own code. This is the difference from the
[hrum](../hrum) plugin: Hrum 3.5, also by Hrumer, makes self-extracting blocks that you run.
## Installation
You need mc and python3 (version 3.6 or later).
```
./install.sh
```
The script puts `hrust` into `~/.local/share/mc/zx/`, adds a rule for F3 on `.p_?` and `.hr2` files to
`~/.config/mc/mc.ext.ini`, and adds three entries to the user menu, `~/.config/mc/menu`. If you do not have your own
`mc.ext.ini` and `menu` yet, the script starts them from copies of the system ones. The previous versions of the files
are kept next to them as `mc.ext.ini.bak` and `menu.bak`. Restart mc after installing. Running the script again updates
the plugin. To uninstall, run `./install.sh --remove`: the program and the plugin's lines are removed, and the files
return to their previous state.
### Manual installation
1. Copy `hrust` into `~/.local/share/mc/zx/` (or any other folder) and make it executable: `chmod +x`.
2. In mc 4.8.29 and later, add these lines to `~/.config/mc/mc.ext.ini` right after the `Version=4.0` line. If the file
does not exist, first copy the system one: `/etc/mc/mc.ext.ini`, or `$(brew --prefix)/etc/mc/mc.ext.ini` with
Homebrew.
```
[hrust]
Regex=\\.(p_.|hr2)$
RegexIgnoreCase=true
View=%view{hex} ~/.local/share/mc/zx/hrust -d %f -
```
In mc before 4.8.29, these lines go at the beginning of `~/.config/mc/mc.ext`:
```
regex/\.([pP]_.|[hH][rR]2)$
View=%view{hex} ~/.local/share/mc/zx/hrust -d %f -
```
3. The menu entries are the contents of the `menu` file in this folder. Append it to `~/.config/mc/menu`, replacing
`@BIN@` with the program's folder: `$HOME/.local/share/mc/zx`. If you have no `menu` of your own, first copy the
system `mc.menu` (from the same folder as `mc.ext.ini`), or the system entries will be gone. The command lines start
with a tab.
## In mc
- **F2, u — "Hrust: pack".** Packs each selected file (the tagged ones, or the current one if none are tagged) as QC
3.11's `h` command did: `game.C` becomes `game.p_C` next to it (see "Names"). Folders are skipped. The sizes are
printed on the console (Ctrl-O shows it). A screen packs in 0.01 seconds, 30 KB in 0.2 seconds.
- **F2, O — "Hrust: pack (oh2c)".** The same, but packed as oh2c does: the shortest block the format allows (2 %
shorter on average), any file up to 65535 bytes. Slower: a screen in 0.1 seconds, 30 KB in about a second.
- **F2, N — "Hrust: unpack".** Unpacks each selected hr2 block: `game.p_C` becomes `game.C`, `pic.hr2` becomes `pic`,
a block with another name `NAME.dpk`. A hobeta file with a block inside is unpacked too.
- **F3 on a `.p_?` or `.hr2` file** shows the unpacked data in the internal viewer, in hex (F4 in the viewer switches to
text).
None of the entries overwrites an existing file. If a file fails (its output exists, it does not pack, it is not a
block), the plugin says why and waits for Enter. N is QC 3.11's key for unpacking ("uNhrust"); QC's `h` and `U` are
taken in mc's own menu. mc runs menu commands only in ordinary folders, not inside images: copy the file out of the
image (F5) and work on the copy.
## Command line
```
hrust [-f] [-q | -o] INPUT [OUTPUT] pack (OUTPUT by default: see "Names")
hrust -d [-f] INPUT [OUTPUT] unpack
```
- `-f` — overwrite OUTPUT. Without it an existing file is left alone, and the program exits with an error.
- `-q` — no lazy matching: QC's other packing mode ("simple pack", bit 3 of its settings off), 1.5–2 times faster on
the Spectrum, a little longer. Also byte for byte as QC.
- `-o` — pack as oh2c does.
- OUTPUT `-` is the standard output.
- `--` — the end of the options: a name after it may start with `-` (`hrust -- -x.C`).
After packing or unpacking, a line like `game.p_C: 6912 -> 2136 bytes` is printed. Errors are printed as `hrust: ...`
with exit code 1, bad usage with code 2.
```
hrust game.C game.p_C
hrust -o -f game.C the shortest block, over the old one
hrust code.bin code.bin.hr2
hrust -d game.p_C game.C
hrust -d pic.hr2 - | hexdump -C | less
```
## QC 3.11's Hrust command
QC 3.11 had the command `h` (Hrust): it packed the file under the cursor and saved the block as a new file on
the disk. QC 3.20 dropped it to make room for other things; its packer stays in QC's sources (`src/hrust/pack.asm`)
behind a build key. It is HRQC, "Hrust 2.4 packer for projects": Hrumer's Hrust 2 with Alone Coder's improvements (the
fix of a loss in packing density, and lazy evaluation). What `h` did:
- It packed files of 2 to 128 sectors (257 to 32768 bytes). The packer works in the top 32K of the Spectrum's memory.
One sector can't get any shorter on the disk, so QC did not pack such files. It did not work in 48K mode, and the
`a` key stopped it. The plugin keeps the upper limit and packs small files too: from 7 bytes as QC's packer does,
below that (the packer needs the data's last 6 bytes and one more) as a stored block, which QC unpacks.
- It asked for the new file's name and offered the old name with the extension `p_` and the type: `game.C` became
`game.p_C`. On the disk this is type `p`, with `_` and the original type in the start field. The length is the
block's.
- It packed with lazy matching (a match one byte later is taken if it is longer) unless bit 3 of QC's settings was
off. It was on by default, and the `s` key switched it.
- The length packed was the catalog's (or, when it did not fit the file's sectors, nearly all the sectors). For a
BASIC file this is the program without its variables. The plugin packs the whole file it is given.
The unpacking command (`n` in 3.11, `U` since 3.20) gives the type back from `p_` and the type, or `C`. In the start
field it writes two spaces: a code file's address and a BASIC program's length are not restored. The length is the
data's.
## The hr2 block
```
+0 "hr2"
+3 flags: #31 ("hr21", Hrust 2.1's format); bit 7 = 1: stored, not packed
+4 the data's length (a word)
+6 the length of what follows, from +8 (a word)
+8 the data's last 6 bytes, as they are
+14 the packed stream of the rest
```
A stored block has the data itself at +8. The stream starts with the data's first byte. Then come tokens, whose bits are
read from the top, in bytes put where their first bit came, with the tokens' whole bytes in between:
| bits | meaning |
|---|---|
| `1` BYTE | a byte as it is |
| `0 00` ddd | a byte from 1–8 back |
| `0 01` BYTE | 2 bytes from 1–256 back |
| `0 10` DIST | 3 bytes |
| `0 11`… xx DIST | 4–15 bytes: `11` for each 3, then the rest in 2 bits (4 = `0 11 01`, 15 = `0 11 11 11 11 11`) |
| `0 11 00 0` nnnn | 12 + 2n bytes as they are (12–42) |
| `0 11 00 1` BYTE | 16–255 bytes; with BYTE 1–15 and one more byte, up to 4095; BYTE 0 is the end |
DIST is `1` BYTE for 1–256 back, or `0` and the high byte of the minus distance in 1, 2, 3 or 4 bits (or whole, after
`0000`), then the low byte. QC's packer looks 16 KB back, oh2c as far as the data goes; QC's depacker takes both. The
headers of `src/hrust/unpack.asm` and `pack.asm` in QC's sources tell more.
## Names
| packing | unpacking |
|---|---|
| `game.C` → `game.p_C` (any one-character extension: a TR-DOS type) | `game.p_C` → `game.C` (`GAME.P_C`: `GAME.C`) |
| `game.$C` (hobeta) → `game.p_C`, packing the file's data, as long as its header says | `NAME.hr2` → `NAME` |
| any other name → `NAME.hr2` (`pic.scr` → `pic.scr.hr2`) | any other name → `NAME.dpk` |
The output is always a plain block, never hobeta. With the [trdos](../trdos) plugin, copy `game.p_C` into an image as
it is: it becomes type `p` with `_C` in the start field, as QC writes it. A hobeta file is recognized by its header's
checksum, as trdos does it: for packing only under a name like `game.$C`, for unpacking whatever its name, if a block
follows the header (then `game.$p` with `_C` in the start field becomes `game.C`).
In an image, the trdos plugin shows a file packed by QC as `game.p`, not `game.p_C`: it shows a three-character
extension only when it is made of lowercase letters and digits. Copy it from the image's `hobeta/` folder instead
(`game.$p`): its header keeps the type, and `hrust -d` gives `game.C`.
## Details and limitations
- **The same as the originals.** The blocks are byte for byte those of QC's own Z80 packer (`src/hrust/pack.asm`, run
in a Z80 emulator), with lazy matching and with `-q`, and with `-o` those of oh2c v2020.01.04 built from its
sources. Unpacking gives what QC's depacker gives. Checked on 6119 files of 257–32768 bytes (42 MB) extracted from
228 TR-DOS images and SCL archives, on every size from 7 to 300 bytes of six kinds of data, and on 322 files made
for the edge cases; with `-o`, also on 723 files of 1–256 bytes and 216 of 32–64 KB (see "Tests").
- **Data that hardly packs, near 32K.** QC's packer builds the block from #7E00 up, below the data, which ends at
#FFFF. When the two together are longer than #8200 bytes, the block lies over the data already packed, and QC limits
its search to what is still there (the plugin does the same). If the data hardly packs, the block overtakes the data
still to be read, and QC 3.11 wrote a broken block, or one cut to 32K. The plugin refuses such data instead
(`hrust: ...: the packed data overtakes the data being packed`, or `... keeps only its first 32768`): 6 of the 6119
files. `-o` packs them. QC 3.20 (with the h command's build key) packs 28K at most for this reason.
- **A quirk kept.** QC compares the lengths of the two matches of lazy matching as bytes, with 255 for 255 and more. A
match of 255 bytes or more with none one byte later counts as "the later one is longer", and both bytes go as they
are. The plugin does the same: 1 of the 6119 files packs 202 bytes longer because of it.
- **oh2c's blocks** are 2 % shorter than QC's on those files (half of the files gain 1.5 % or more, a few up to 28 %);
without lazy matching (`-q`) QC's are 0.2 % longer. oh2c looks back as far as the data goes, QC 16K. It stores the
data (bit 7 of the flags) when the stream would not be shorter. It takes up to 65535 bytes, as the original does; a
TR-DOS file holds 65280 at most.
- **Small and empty files.** Below 7 bytes both ways give a stored block, as oh2c does. An empty file is refused: oh2c
would store it in 8 bytes, but QC's depacker runs wild on such a block (it copies 0 bytes as 64K), and QC 3.20's
unpacker refuses it. `-d` refuses it too.
- **Unpacking.** A block that is cut, that is empty (its data's length 0, or the length of the rest), whose stream gives
another length than its header, or whose match points before the start of the data, is refused. Bytes after the block
are not read (a file in whole sectors). QC 3.20 unpacks data of up to 58012 bytes (QC 3.11: up to 32768); the plugin
unpacks any. QC 3.11's `n` unpacked in place, the block moved to end where the data ends: a block whose data packs
badly at its end comes out spoilt there (44 of 388 blocks tried, all of data that hardly packs). QC 3.20's `U` leaves
room for that.
### Speed
QC's packer takes its matches from chains of the earlier places; the plugin finds the same ones with Python's own
search in memory. oh2c tries every distance at every place (its time grows as the square of the length); the plugin
gets the same result from the nearest distances where the match grows only. So on usual data the port is faster than
the original:
```
hrust QC on the Spectrum hrust -o oh2c in C
a screen, 6912 bytes 0.01 s 19 s 0.1 s 0.2 s
text, 30000 bytes 0.2 s 81 s 0.8 s 4.4 s
```
(Intel Core i7-9750H, Python 3.14; QC at 3.5 MHz, with lazy matching, and half the time with `-q`.) Data made of
few different bytes is slower with `-o`: 30 KB of random 0s and 1s takes 4 seconds (oh2c: 7). On data where a match
grows at many distances one after another, the port is slower than oh2c, 5–7 times: 48 KB of runs of `a` of growing
length, each ending in `b`, take about 150 seconds (oh2c: 22).
## Tests
```
python3 -B -m unittest discover -s tests
HRUST_CORPUS=~/files python3 -B -m unittest discover -s tests # also every file in the folder, packed and unpacked
HRUST_CORPUS=~/files HRUST_OH2C=~/oh2c/oh2c python3 -B -m unittest discover -s tests # -o compared with oh2c
```
`tests/vectors/` holds files and the blocks QC's own Z80 packer made of them in a Z80 emulator, with lazy matching and
without (`.lazy.hr2`, `.quick.hr2`), and oh2c's (`.oh2c.hr2`); `vectors.txt` has the checksums of the blocks of the
larger data the tests make. The folder of `HRUST_CORPUS` is only read. To build oh2c on Linux or macOS, give its
`main.cpp` and `compress.cpp` a stand-in for `Windows.h` (the type `byte`, `ARRAYSIZE`, `min` and `max`), and remove
`Compressor::` inside the class in `compress.h`.
## Credits and licence
Hrust 2 — the format and its packer and depacker — is by Hrumer (Dmitry Pyankov, 1998–99). HRQC, "Hrust 2.4 for
projects", is Alone Coder's improved version of the packer; QC 3.11 packed with it, and the plugin's packer follows QC's
Z80 code of it (QC's `src/hrust/pack.asm`). The depacker follows QC's, which comes from Hrumer's DeHrust 2.x. oh2c,
the optimal Hrust 2 packer, is by Eugene Larchenko, <https://gitlab.com/eugene77/optimal-hrust-compressor>, under the
MIT licence; the plugin's `-o` is a port of it, under the same licence (the file `LICENSE-oh2c`).
## Copyright
Copyright © 2026 Spectre (Optical Brothers), https://www.zxby.org
MIT License: see [LICENSE](LICENSE). `-o` is a port of oh2c, whose MIT licence is in [LICENSE-oh2c](LICENSE-oh2c).