[sword-devel] module driver reorganization proposal

[John Austin]

This sounds great! Hopefully this will also result in adding support for 
compressing RawCom4 commentaries? Currently this is not possible, but 
would sure be great to have. Thanks Chris!
-John


On 03/18/2014 12:43 PM, 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.
>
> --Chris
>
>
>
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page