[sword-devel] Miscellaneous Sword API Questions

[Joachim Ansorg]

Hi,

> 1.) Can I rely on the values from the "Testament()" function within
> VerseKey? In other words, will the Old Testament always be 1 and the New
> Testament 2? Would the Apocrypha, for example, be 3?  Or would it be 2 and
> push the New Testament back to 3?  Would the New Testament still be 2 in a
> NT-only translation?  For the purposes of BibleMemorizer's plugin system,
> the same testament identifier in the uBook needs to be consistent across
> translations and across plugins.  A reference to the book of Mark should
> always refer to the book of Mark, not the second book of the Apocrypha.  It
> need not be the same as Sword if a consistent algorithm can be used to
> convert the two.  (API suggestion:  There should be a consistent way to do
> this.  An enum would make this very easy.)

Testament() gives you 1 for the OT and 2 for the NT, even for NT-only bibles. 
The apocrypha are not yet supported

> 2.) What is the most efficient way to tell if Sword recognizes a particular
> book?  I would like the Sword plugin to fall back onto using the uBook if
> the book name passed to it is not recognized, but only then.  Users will
> not see the uBook unless they manually browse the XML output, so the book
> name should be the primary determination to avoid unexpected behavior.

I guess you can use VerseKey::Error() to check if the key is valid.
e.g.
VerseKey vk("Invalid_bookname");
if (vk.Error() ) ... //an error occured

(Untested :)

> 3.) What is the best way to check how many chapters a given book has?  Is
> there a function that returns this, or do I need to deal with the struct
> that has this information?

You can look into bindings/swig/versekey.i, which has a sample implementation 
how to get the number of chapters of a book.

> 4.) Does Sword use UTF-8 encoding by default?  Is there a way to globally
> force UTF-8 usage, or would I have to manually convert with the functions
> in the *utf8.h files?  (For consistency, I would like the plugins to always
> use UTF-8 for strings.  I plan to use char arrays instead of QStrings so
> that the plugins might me more generally useful to other programs that just
> need simple features from Sword or any other interface for which a plugin
> may be written.)

Have a look at the class StringMgr. If you set a reimplementation which 
supports unicode you can make sure that all VerseKeys will use UTF-8 and that 
the -utf8 locales files are used.
BibleTime's CVS has a QtStringMgr implementation which uses QString.

> 5.) Is there a way to prevent Sword from accepting verses like "Romans
> 1:40" and then parsing them to (in this case) "Romans 2:8"?  This behavior
> might not be what users expect.  Is there a way to check if the verse
> reference is really valid?

I think you should call AutoNormalize(0) on a VerseKey to disable that.
Use Error() to check if a key is valid.

> 6.) Does Sword offer categorizations of the books of the Bible (e.g.
> "Gospels" and "Prophets")?  I know BibleTime has these categorizations
> available when searching.  Is this a BibleTime feature or a Sword feature? 
> If it is a Sword feature, how is it accessed?

It's a BibleTime feature. We use a ListKey and pass it to the module search.


Joachim
-- 
<>< Re: deemed!
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://www.crosswire.org/pipermail/sword-devel/attachments/20050420/19230bdb/attachment.bin