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

[Jonathan Morgan]

On Tue, Jun 3, 2008 at 7:16 PM, Simon J Mackenzie <smackoz at fastmail.fm> wrote:
> Appreciate the prompt reply!
>
> On Tue, 3 Jun 2008 17:13:46 +1000, "Ben Morgan" <benpmorgan at gmail.com> said:
>
> 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.
>>
>>
>
> Thank you this all makes sense now.
>>
>> 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.
>
> Using the mod I proposed provides me enough to work with. An array of single
> verse entries I can use to extract some biblical text.
>
> 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))
>
> d) using the flatapi bindings with D programming language, see
> www.digitalmars.com.
>
> For my joint managed congregarions here in Thailand I print the Lectionary
> Readings for each Sunday. This is currently done manually and is time
> comsuming and inefficient use of my time. In my spare time I've began
> writing a small program in D to extract a set of Lectionary readings
> (already working) for a given range of Sundays (tabulated text file of
> Lectionary readings) and format the extracted Lectionary readings (working
> on this now) for import into OOo Writer for final layout and printing with a
> minimum of user intervention. This has also been an opportunity for me to
> evaluate the D programming language for future projects (I used to be a
> programmer in my former life) which has been an enoyable experience.
>
> As I was looking over the flatapi code I started thinking ahead and was
> wondering what the status of this code was. Your comment confirmed that
> flatapi.cpp/h is far from complete but it is sufficeint for the needs of my
> current small project. What the future holds remains to be seen.

It seems likely that SWIG bindings will be better maintained than
flatapi.  If your needs are simple, then flatapi is fine.  But you may
want to consider moving to a SWIG based solution if your needs are
likely to go beyond flatapi.  There appears to be some support for D
and SWIG at http://www.wikiservice.org/wiki4d/wiki.cgi?DwithSwig, but
of course I can't tell you whether it will actually work with Sword.
If it does, then you will get a much greater coverage of the Sword
API.

Jon