[sword-devel] module driver reorganization proposal

[Jaak Ristioja]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 18.03.2014 08:43, Chris Little wrote:
> 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.

Good idea! But I'm not sure whether passing such an argument to the
constructor is a good idea. I'd rather use templates and type traits
for this if we only want to support a few cases (16, 24, 32 and maybe
40 bits).

Blessings,
Jaak
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

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
9TqqZv7ml5T7r8SMd8Ji
=k7Vn
-----END PGP SIGNATURE-----