The SWORD Engine API Primer

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 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 descendant 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 descendant for use with a module object, the module's 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 calling SWModule's getKey() method or 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. Here is an example obtaining one modules's SWKey and using it to traverse both that module and setting another module to the same key.

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 = (VerseKey *) webster.getKey();

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

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

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

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

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

for (searchResults = TOP; !searchResults.popError(); searchResults++) {
	webster.setKey(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

#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;
}