[sword-devel] module driver reorganization proposal

[Troy A. Griffitts]

On 03/18/2014 07:58 AM, DM Smith wrote:
> Chris,
>
> Your suggestion is very similar to JSword's implementation. It has simplified code maintenance.
>
> There are three types of module files: index, compression index and data files. It may do well to handle these separately.
> The index consists of fixed sized entries consisting of parts. For a raw module it is: offset and size.  For a compressed module it is: block, offset and size.
> The block and offset are always 32bits. But it is the size that varies in width. Today, either 2 or 4 bytes.

SWORD C++ has this same separation.  The work to deal with the index 
files is primarily isolated in src/modules/common/.  These classes are 
used by the drivers to do the work.  They are not intended as part of 
the outward-facing interface to the engine, but simply for code reuse in 
the implementation details.

I support the removal and *4 variants of the drivers.  This probably 
should have always been an extended property of the original drivers.

> Also, I don't see the point of the 3 byte entry. The only thing it affects is the size of the index file. In memory it will be 32bit. For a Bible it would save about 65K to have a 3 byte rather than a 4 byte.
I don't mind the 3 byte derivative.  There is no reason to store an 
extra byte in every record of the index if it will never practically be 
used (not once by any module we currently have).

> On Mar 18, 2014, at 2:43 AM, Chris Little <chrislit at crosswire.org> wrote:
>> My proposal is to collapse the above classes into three classes:
>> RawText, zText, and RawLD

I like the removal of the *4 classes, but I don't like the collapse of 
the Text and Com concepts.  I have never like that SWCom is basically 
duplicate logic from SWText with very very differences (I think 
increment and decrement might be different, but not ever sure anymore.  
This might suggest I'd be in support of the collapse, but I am not.  The 
concept of a Commentary is very different than that of the text on which 
it comments.  I realize that the current implementation in SWORD is 
practically identical right now, as we only have per-verse commentaries, 
but the concept is important to keep separate.  SWCom should not extend 
SWText.  Even though this would allow us to save some code duplication 
right now, most of that duplication has already been factor into the 
src/modules/common/*verse classes that deal with per-verse material.  I 
think it is important to keep the concept of a commentary distinct for 
future purposes we cannot foresee right now.  Though I can sympathize 
with the desire to remove the redundancy.

>> 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.

These method signatures should primarily be isolated to the internal 
src/modules/common/ classes and shouldn't effect the public API much, if 
at all.  We started using our own exact primitive types a few years back 
for implementation details which needed exact types across all 
platforms, so please use __u32.


>> 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.

I like this for backward compatibility, but I think we should have an 
EntrySize or similar in the .conf files.  This let's us maintain the 
ModDrv=<real SWORD class name> paradigm in case we ever really do make 
it to dynamically loadable drivers in some future release.

>> 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.
See comments from earlier.  I think it is important to maintain the 
SWCom distinction and that SWCom should not conceptually inherit SWText, 
though I do understand why you propose such to reduce code duplication.

Thanks for the proposal Chris,

Troy