[sword-devel] module driver reorganization proposal

[Chris Little]

We've got quite a few classes in Sword that essentially duplicate code 
found elsewhere in Sword, with minor changes. The module drivers are a 
prime example.

Specific examples include RawText & RawText4, RawCom & RawCom4, zText & 
zText4 (new as of today), zCom & zCom4 (new as of today), and RawLD & 
RawLD4, each pair of which differs in that one member uses a 16-bit 
value to store entry size and the other member uses a 32-bit value. (The 
16-bit sizes permit entries up to 64KiB; the 32-bit sizes permit entries 
up to 4GiB.)

There are also the pairs RawText & RawCom, RawText4 & RawCom4, zText & 
zCom, and zText4 & zCom4, each pair of which differs very little.

My proposal is to collapse the above classes into three classes:
RawText, zText, and RawLD

Each of these classes would support entry sizes of 2, 3, or 4 bytes 
(16-bit = 64KiB entries, 24-bit = 16MiB entries, 32-bit = 4GiB entries). 
Internally, the classes would always store sizes as a uint32_t, but 
would serialize as 2, 3, or 4 byte size integers, depending on the 
parameters passed to the constructor. This will necessitate changing 
many of the class method signatures to accept uint32_ts instead of 
shorts & longs.

Similarly, the classes zVerse & zVerse4, RawVerse & RawVerse4, and RawLD 
& RawLD4 would be condensed into zVerse, RawVerse, & RawLD capable of 
reading files with 2, 3, or 4-byte entry sizes.

This would not require changes to existing modules. A RawLD4 module will 
still work, but we'll use the RawLD driver to read it and parse the '4' 
form the end of the driver name to determine that we will read 4-byte 
entry sizes.

RawCom, zCom, & SWCom classes would then be derived from RawText, zText, 
& SWText respectively. Maybe we can even eliminate the *Com classes and 
simply add a member variable to indicate whether to act like a 
commentary or a Bible.


Advantages of this proposal include all of the things that come with 
reduced code duplication:
Less code, reduced API complexity, smaller library size, etc.
Greater consistency, without having to page through half a dozen 
distinct classes to keep code consistent.
Bugs only need to be fixed in one location instead of many.
Whatever else makes DRY practices better than WET.

The method described also makes it trivial for us to add the 3-byte 
entry size drivers, which should be enough for anything practical (up to 
16MiB per entry). And down the road, we could add 5-byte entry size 
support with ease for entry sizes up to 1TiB. (No, I'm not suggesting that.)

If you're wondering why RawGenBook & zLD are left out of the proposal, 
it's because they both use 4-byte entry sizes already and no 2-byte 
versions exist.

--Chris