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.

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:

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.

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:

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:

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:

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: