[sword-devel] SWIG Bindings (Was: Re: What is a Sword module?)

[Greg Hellings]

On Thu, Nov 4, 2010 at 10:04 PM, Troy A. Griffitts <scribe at crosswire.org> wrote:
> On 11/05/2010 02:41 AM, Greg Hellings wrote:
>> ... would require some effort to be
>> put into the SWIG bindings to provide especially a missing binding for
>> the STL multimap class.
>
> Yeah, in C++ it is nice to be able to access entryAttributes as a
> dynamic map:
>
> SWBuf word1Morphology =
>  module.getEntryAttributes()["Words"]["001"]["Morph"];

Dynamic map is all fine and good, and every scripting language we try
to bind to has great support for this, although the names differ from
language to language.  In PHP it's called and "associative array" in
Python it is called a "dictionary" and I forget the name in Perl.  The
ability in those languages usually extends to being able to place any
object that is comparable as the key of the array and receive any
other element back as the value.

But the nature of multimap is different - and I'm confused as to how
it is used at all.  What you are showing above I would call a
multi-dimensional associative array/dictionary.  I make them all the
time in Python and PHP.  But a multimap is defined as "a
generalization of a map or associative array abstract data type in
which more than one value may be associated with and returned for a
given key."  I don't think we are actually using multimap
functionality but rather just a multidimensional array.

SWIG gives us multimap support in Python for free and I found a
version we include with the library to get Perl working.  However,
SWIG does not have an implementation of stl::multimap for us, so we
either need to write one, or refactor our multimap usage to be nested
associative arrays.

>
> But this interface doesn't translate well to other languages.  I have
> had to implement a different interface for my custom language binding
> for Java-jni (used by SWORD C++ on Android) and CORBA (used by SWORDWeb).
>
> The binding interface I usually implement is described in simple IDL
> here and is a fairly concise set of methods that give access to most all
> of functionality of the engine:
>
> http://crosswire.org/svn/sword/trunk/bindings/corba/swordorb.idl
>
> You'll notice the method for obtaining entry attributes:
>
> StringList SWModule.getEntryAttribute(in string level1, in string
> level2, in string level3, in boolean filtered);
>
> This less exotic interface maps much easier to other languages, but
> implies you know what attribute you'd like to obtain (discovery by
> iteration is not supported, but really, what frontend does that anyway?)
>
> So, in summary, maybe we should add this to swmodule.i

That is one possibility.  However, I think there are other places
within the bindings that should be addressed first.  As you saw
yourself, SWBuf plays great in C++ but SWIG doesn't seem to pick up
any ability to auto-cast it back to a Python string/unicode object.
At the very least, that functionality should be as easy as an explicit
cast of unicode(myswbuf) and better yet it would be transparent.

Ideally, someone would write extra Python code so that the SWIG
bindings were wrapped in a more naturally Pythonic binding.  It might
be perfectly natural in a language like C++ or Java to access a module
with

SWMgr* mgr = new SWMgr(FMT_HTMLHREF);
SWModule* mod = mgr->getModule("KJV");
VerseKey* key = (VerseKey*) mod->getKey();
key->persist(true);
key = 'john 3:1';
cout << mod->RenderText();

A natural pythonic way of doing this would probably look more like

mod = Sword.module('KJV')
print mod('john 3:1', format='HTMLHREF')

But in order to get to that point would take someone writing
native-feeling Pythonic bindings and making design decisions like
that.  I'm tied up with other tasks at the moment and can't devote the
time to learning SWIG to clean up the warnings and errors the bindings
throw on compile PLUS write native feeling bindings for languages.
But it'd be a great thing for someone to tackle if they really like
their scripting languages and probably wouldn't require learning much
(if any) C++.

I fully intend to get to this, but my energies will be in the Wycliffe
work I'm doing plus maintaining the CMake tool chain for the
foreseeable future.

--Greg