DevTools:SWORD

Documentation

The SWORD Engine API Primer

The API primer is quite old and has not been updated for a long time.If in doubt, consult the API Doxygen documentation (see below) and look at code samples within the source tree under /examples

This short introduction gives a brief review of the underlying classes of the The SWORD Engine's interface. Understanding this tutorial will give a good foundational knowledge necessary for building applications with The SWORD Engine API. This tutorial begins by showing the 'hard' way to do things. This understanding is foundational for learning 'how things work' in the world of SWORD; but don't get discouraged, there are higher level factories which are explained later, which hide much of this elementary work.

Section 1 - SWModule / SWKey / SWFilter

The SWModule class is probably the most important core object in the API. Every module descends from it. Immediate descendants include subdivided module types such as: SWText (Bible texts), SWCom (commentaries), SWLD (lexicons and dictionaries). Descendants of these subdivided types are specialized Module 'drivers', including RawText (descends from SWText and reads raw text data files), RawCom, zText (SWText descendent that reads compressed data files), etc.

The most fundamental use of an SWModule is to retrieve an indexed piece of information from a Module. This is performed by positioning the SWModule to the correct index with an SWKey object via the setKey() method. After the SWModule is positioned to the correct index, the information can be retrieved most fundamentally by calling the RenderText() method or by casting the object to a (const char *). Here is an example of such:

RawText webster("modules/texts/rawtext/webster/", "Webster", "Webster Text");
webster.setKey("jas 1:19");
cout << webster->RenderText();

The setKey() method takes an SWKey object. An SWKey object can be constructed with a string (const char *), thus the previous call to setKey() is valid.

Most SWModule descendants use custom SWKey descendants to make navigation easier. The example above uses the RawText module type which descends from SWText. SWText defines its SWKey type as the SWKey descendent VerseKey. VerseKey knows all about the canonical books / chapters / verses of the Christian Bible and thus parsed 'jas 1:19' appropriately. If it is necessary to create a specialized SWKey descendent for use with an object, the CreateKey() method can be called. This method is overridden in each SWModule that would prefer to use specialized SWKey descendants. The object returned by CreateKey() MUST BE DELETED by the caller.

An SWModule's current SWKey can be obtained by casting the SWModule to an (SWKey &) or (SWKey *). This gives access to the actual SWKey object currently associated with the SWModule. Changing the value of this SWKey will change the position of the SWModule. If only a textual representation of an SWModule's SWKey is desired, a call to getKeyText() will provide such. An SWKey can be shared between modules by setting the SWKey to 'persistent' using the Persist(true) method call and subsequently setting multiple modules to this SWKey using calls to their .setKey() method. Example:

RawText webster("modules/texts/rawtext/webster/", "Webster", "Webster Text");
RawCom mhc("modules/comments/rawcom/mhc/", "MHC", "Matthew Henry's Commentary on the Whole Bible");

VerseKey mykey;

mykey.Persist(true);

webster.setKey(mykey);
mhc.setKey(mykey);

for (mykey = "jas 1:1"; mykey.Chapter() == 1; mykey++) {
cout << webster.getKeyText() << ":\n";
cout << (const char *) webster << "\n";
cout << "-------------\n";
cout << (const char *) mhc << "\n";
}

SWModule positions can also be changed by equating or incrementing using = TOP, = BOTTOM, ++, --, +=, -=. A call to .Error() should subsequently be made to ensure a valid navigation. Example:

for (webster = TOP; !webster.Error(); webster++) {
cout << (const char *) webster;
}

Searching can be performed on an SWModule by calling the search() method. This method returns an SWKey descendent called SWListKey. An example follows:

SWListKey &searchResults = webster.search("knees");

searchResults.Persist(true);
webster.setKey(searchResults);

for (searchResults = TOP; !searchResults.Error(); searchResults++) {

cout << (const char *) searchResults << ":\n";
cout << (const char *) webster << "\n";
}

SWModules can contain one or more SWFilters for rendering their text to the appropriate formats. SWFilters are added to an SWModule using the AddRenderFilter() and AddStripFilter() methods. Render filters filter the text for display whereas Strip filters filter the text to a raw form used by such as the search functions. Typical SWFilter descendants include: GBFPlain (filters from General Bible Format (GBF) to Plain Text), GBFRTF (GBF to Rich Text Format), RWPRTF (filters special greek tags in Robertson's Word Pictures to Rich Text Format).

Section 2 - SWMgr / MarkupFilterMgr / SWConfig

SWMgr is a high level factory which is more typically used by a frontend developer to access all of the installed modules on a system.

SWMgr can work in conjunction with MarkupFilterMgr to insure a desired markup output by automatically adding appropriate SWFilter objects to all SWModule objects. A number of output formats are supported. Here is an example of how to construct an SWMgr which will return HTML output from all SWModule objects when rendering:

SWMgr manager(new MarkupFilterMgr(FMT_HTMLHREF));

By default, SWMgr attempts to find installed modules by a series of hierarchical lookups for systemwide, user, or working directory configuration files. For our example we will assume there is a module installed with a configure file as follow:

[KJV]
DataPath=./modules/texts/rawtext/kjv/
ModDrv=RawText
SourceType=GBF
GlobalOptionFilter=GBFFootnotes
GlobalOptionFilter=GBFStrongs
Feature=StrongsNumbers

SWMgr reads its configuration files and constructs an SWModule for each section contained therein. This allows a frontend developer to instantiate an SWMgr and then query for all installed modules. The SWMgr makes its SWModule objects available in two ways. First, an SWModule object can be retrieved by name with a call like:

SWMgr library;
SWModule *kjv = library.getModule("KJV");

More dynamically, all SWModule objects can be discoved via an exposed STL map object. A typedef for the appropriate map pair is defined for the developer in swmgr.h as follows:

typedef std::map<SWBuf, SWModule *, std::less<SWBuf>> ModMap;

The first of the pair is the 'name' of the module, e.g. "KJV". The second is a pointer to the actual SWModule object. A public ModMap member called Modules is present in SWMgr. The following example prints out a verse from all installed Bible Text modules:

SWMgr library;
ModMap::iterator modIterator;

// Loop thru all installed modules and print out information
for (modIterator = library.Modules.begin(); modIterator != library.Modules.end(); modIterator++) {
SWBuf modName = (*modIterator).first; // .conf [section] name (also stored in module->Name())
SWModule *module = (*modIterator).second;
if ((!strcmp(module->Type(), "Biblical Texts")) {
module->setKey("jas 1:19");
cout << modName << ": " << (const char *) *module << "\n";
}
}

SWMgr uses the SWConfig utility class to manage its configuration files. SWMgr makes available an SWConfig object member called config.

SWConfig reads sectional INI type files and makes available the data therein via a nested map. Typedefs for the appropriate map pairs are defined for the developer in swconfig.h as follows:

typedef multimapwithdefault<SWBuf, SWBuf, std::less<SWBuf>> ConfigEntMap;
typedef std::map<SWBuf, ConfigEntMap, std::less <SWBuf>> SectionMap;

There is an operator[](const char *) available to get the desired section from the SWConfig object. An example to access the DataPath in our KJV example section above follows:

SWMgr library;

cout << library.config["KJV"]["DataPath"];

You can use the SWConfig class to create and read your own INI style configuration files. Construct an SWConfig object with the filename on which it will work. Methods Load() and Save() will migrate data between the object and the data file. An example of creating a datafile with SWConfig follows:

SWConfig screenInfo("./layout.conf");

screenInfo["Main Window"]["Left"] = "100";
screenInfo["Main Window"]["Top"] = "100";
screenInfo["Main Window"]["Width"] = "400";
screenInfo["Main Window"]["Height"] = "300";

screenInfo["Search Frame"]["Visible"] = "false";

screenInfo.Save();

Section 3 - Bringing It All Together

The following is an example included in the SWORD engine source code. You should be able to read this entirely through now:

#include <stdio.h>
#include <iostream>
#include <stdlib.h>
#include <swmgr.h>
#include <swmodule.h>
#include <markupfiltmgr.h>

using namespace::sword;

int main(int argc, char **argv)
{
	SWMgr library(new MarkupFilterMgr(FMT_PLAIN));
	SWModule *target;

	if (argc != 3) {
		fprintf(stderr, "\nusage: %s <modname> <\"lookup key\">\n"
							 "\tExample: lookup KJV \"James 1:19\"\n\n", argv[0]);
		exit(-1);
	}

	target = library.getModule(argv[1]);
	if (!target) {
		fprintf(stderr, "Could not find module [%s].  Available modules:\n", argv[1]);
		ModMap::iterator it;
		for (it = library.Modules.begin(); it != library.Modules.end(); it++) {
			fprintf(stderr, "[%s]\t - %s\n", (*it).second->Name(), (*it).second->Description());
		}
		exit(-1);
	}

	target->setKey(argv[2]);

	target->RenderText();    // force an entry lookup first to resolve key to something pretty for printing below.

	std::cout << target->getKeyText() << ":\n";
	std::cout << target->RenderText();
	std::cout << "\n";
	std::cout << "==========================\n";
	std::cout << std::endl;
	return 0;
}

API Documentation

See The SWORD Project - API documentation for the current (or very nearly current) SVN HEAD. Starting with the next version of the documentation (post 1.5.11), there will also be other documentation placed there for developers to keep track of.

Locale file layout

A locale file is stored in the locales.d folder under the Sword path. The file name is generally the language code with extension .conf

Locales require a few things. Let's step through the German locale:

excerpts from /sword/locales.d/de.conf:

[Meta]
Name=de
Description=German

The above information is used to define the locale. They should be fairly obvious. Name should be taken from a standard abbrev, probably returned from echo $LANG. Please understand that this, and all entries are case sensitive.

The following entries are translation strings for anything you might want. REQUIRED are the book names of the Bible. Other things might be option name, value, tip, translations, or any text returned from the engine. It may not work right now, but if it doesn't, please post a message that you found a constant string in the engine not being translated.

[Text]
Genesis=1. Mose
Exodus=2. Mose
Leviticus=3. Mose

# <snipped rest of book names>

[Book Abbrevs]
1 C=1Cor
1 CHRONICLES=1Chr
1 CORINTHIANS=1Cor
1 JN=1Jn

These are the abbreviations for each book and are REQUIRED for the locale to work correctly in the engine. They are actually more than just abbreviations; they tell the parser how to incrementally parse versekey text. Notice that 1 Chronicles would come, alphabetically before 1 Corinthians. The above entries say: 1Cor (which is the OSIS book id for 1 Corinthians) has precedence up through "1 C", any character beyond that will disambiguate the entry anyway, so the default 1 CHRONICLES or 1 CORINTHIANS entries would take over from there.

Please note that the English abbreviations are no longer required to be in the abbreviations section as they are in there by default; in the example above they are in there for demonstration purposes.

IMPORTANT:

There MUST be at least 1 abbreviation entry for each book name comprised of a toupper (uppercase function) of the entire string EXACTLY as you have translated it in the [Text] section.

Following are the REQUIRED entries from our excerpt book names above.

1. MOSE=Gen
2. MOSE=Ex
3. MOSE=Lev

That's it for requirements. Tuning your locale can be important for the user experience. Many [Book Abbrevs] entries may be added to assign precedence if, for example, you find you are getting taken to the wrong entries from text like: "Ma 1:1" (would be Malachi by default because of alphabetical precedence, but might want Matthew or Mark). In this case, you would put in an entry MA=Matt or MA=Mark

You can test your locale with the sword/tests/parsekey test program (this program is in the SWORD source along with several other programs that are used to validate the configuration files) and try different strings to see how they parse.

Note that punctuation characters commonly used in verse references are not allowed in localized book names. These include the hyphen '-' (used for verse ranges), the colon ':' (used to separate chapter and verse numbers), and the comma ',' (used for verse lists). Additionally, numerals in non-initial position are not permitted in book names (i.e. '3John' is valid but 'Psalm151' is not).

Submissions should be sent to sword-support@crosswire.org