[sword-devel] module driver reorganization proposal

Tue Mar 18 07:08:17 MST 2014

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

On 18.03.2014 15:46, Jonathan Morgan wrote:
> On Tue, Mar 18, 2014 at 6:24 PM, Jaak Ristioja <jaak at ristioja.ee 
> <mailto:jaak at ristioja.ee>> wrote:
> 
> 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).
> 
>> As I understand it, this configuration is coming from the conf
>> file at least sometimes (and maybe always).  That sounds to me
>> much more like a property is needed, not a type trait.  Does that
>> make sense?

What do you mean by "property"?

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

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
LL5rainy1hlFV9wqrQVy
=syfo
-----END PGP SIGNATURE-----