[sword-devel] Sword API Questions / Proposal >> flatapi.cpp / flatapi.h

[Ben Morgan]

Hi,

Some answers below...

On Tue, Jun 3, 2008 at 4:45 PM, Simon J Mackenzie <smackoz at fastmail.fm>
wrote:

>  I have been attempting to familiarise myself with flatapi.cpp/h for a
> small in house project but have come up with a few questions about the Sword
> API, particularly flatapi.cpp/h.
>
> 1) The function listkey_getVerselistIterator in flatapi currently accepts
> two parameters but I fail to see the difference / dissimilarity between the
> two parameters "char * list" and "char * key"? Could someone please point me
> in the right direction? Thank you.
>
The list is the actual text you want parsed. The key is some form of
context. Thus a list of "6:1-12" and a key of "John 3:16" will give John
6:1-12.

>
>
> 2) Is there any reason why the function listkey_getVerselistIterator in
> flatapi.h does not accept a boolean flag for normalising a bible reference
> such as "John 6:1,12-16"?
> The current call to listkey_getVerselistIterator produces a "verses" array
> containing [John 6:1, John 6:12] and not [John 6:1, John 6:12, John 6:13,
> John 6:14, John 6:15, John 6:16] as would be expected.
>
Currently the flatapi does not allow proper parsing of biblical references.
Even with your proposed change, it will not allow you to get at what you
want.
The listkey that is returned in the contains keys.
Each key is either a single verse (such as John 6:1)
or a contiguous range of verses (such as John 6:12-16)

Thus under python you can do:
>>> lk=vk.ParseVerseList("John 6:1,12-16", "", True)
>>> lk.getElement(0).getRangeText()
'John 6:1'
>>> lk.getElement(1).getRangeText()
'John 6:12-John 6:16'

However, the flatapi implementation uses getText, not getRangeText, so it
doesn't return the ranges. Updating it to do this should result in it
working. Note that the boolean flag you are wanting added controls whether
the ranges appear, or just the first verse in each range.

However, I don't believe the flatapi bindings  are used at all, and are not
likely to be updated. They implement a very small portion of the bindings.
I'm not sure exactly what you are trying to do, but trying to do it using
one of the three methods below is likely to work much better:
a) Python with the swig bindings - this is the approach BPBible uses.
b) using c++ - like almost all Sword clients do
c) using java, with either JSword (like BibleDesktop) or the corba bindings
(as the web interface does (I believe))

>
> If there is no limiting factors I propose an update to flatapi.cpp and
> flatapi.h as set out below.
>
> === flatapi.h ===========================================
> *// Existing   //* SWHANDLE SWDLLEXPORT listkey_getVerselistIterator(const
> char * list, const char * key)
> *// Proposed //** SWHANDLE SWDLLEXPORT listkey_getVerselistIterator(const
> char * list, const char * key**, bool expandRange**);*
> === flatapi.h ===========================================
>
> === flatapi.cpp =========================================
> *// Existing   //* SWHANDLE listkey_getVerselistIterator(const char *
> list, const char * key)
> *// Proposed //** SWHANDLE listkey_getVerselistIterator(const char * list,
> const char * key**, bool expandRange = false**) { **// set to false by
> default to retain existing function call behaviour.*
>     VerseKey versekey;
>     static ListKey verses;
>
>     versekey.setText(key);
>     verses.ClearList();
> *// Existing   //* verses = versekey.ParseVerseList(list, versekey);
> *// Proposed //** verses = versekey.ParseVerseList(list, versekey**,
> expandRange**);*
>     return (SWHANDLE)&verses;
> }
> === flatapi.cpp =========================================
>
>
>
> As I am new to this group if there is a more appropriate procedure for
> presenting my proposal and having it incorporated in the Sword project
> please let me know.
>
> Any comments would be appreciated.
>
> Regards
> Simon
>
> _______________________________________________
> 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
>



-- 
God Bless,
Ben
-------------------------------------------------------------------------------------------
The Lord is not slow to fulfill his promise as some count slowness,
but is patient toward you, not wishing that any should perish,
but that all should reach repentance.
2 Peter 3:9 (ESV)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.crosswire.org/pipermail/sword-devel/attachments/20080603/c1f88a2e/attachment.html