[sword-devel] module driver reorganization proposal

John Austin gpl.programs.info at gmail.com
Thu Mar 27 23:50:49 MST 2014

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!

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

More information about the sword-devel mailing list