Difference between revisions of "DevTools:SWORD"

From CrossWire Bible Society
Jump to: navigation, search
(See also: Category:SWORD)
 
(22 intermediate revisions by 5 users not shown)
Line 1: Line 1:
= Documentation =
+
== Documentation ==
  
== API Documentation ==
+
=== The SWORD Engine API Primer ===
See [http://www.crosswire.org/~ghellings/svnclassdocs/ 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.
+
''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.
 +
 
 +
=== 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).
 +
 
 +
=== 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:
  
== Locale file layout ==
+
<pre>SWConfig screenInfo("./layout.conf");
  
Requires update!! Not correct after 1.5.11
+
screenInfo["Main Window"]["Left"] = "100";
 +
screenInfo["Main Window"]["Top"] = "100";
 +
screenInfo["Main Window"]["Width"] = "400";
 +
screenInfo["Main Window"]["Height"] = "300";
  
Locales require a few things.  Let's step through the German locale:
+
screenInfo["Search Frame"]["Visible"] = "false";
  
excerpts from /sword/locales/de.conf:
+
screenInfo.Save();</pre>
  
[Meta]
+
=== Bringing It All Together ===
Name=de
+
The following is an example included in the SWORD engine source code. You should be able to read this entirely through now:
Description=German
 
  
The above information is used to define the locale.  They should be
+
<pre>
fairly obvious. Name should be taken from a standard abbrev, probably
+
#include <stdio.h>
returned from echo $LANG.  Please understand that this, and all entries
+
#include <iostream>
are case sensitive.
+
#include <stdlib.h>
+
#include <swmgr.h>
The following entries are translation strings for anything you might
+
#include <swmodule.h>
want. REQUIRED are the book names of the Bible.  Other things might be
+
#include <markupfiltmgr.h>
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]
+
using namespace::sword;
Genesis=1. Mose
 
Exodus=2. Mose
 
Leviticus=3. Mose
 
 
# <snipped rest of book names>
 
 
[Book Abbrevs]
 
1 C=46
 
1 CHRONICLES=13
 
1 CORINTHIANS=46
 
1 JN=62
 
  
These are the abbreviations for each book and are REQUIRED for the
+
int main(int argc, char **argv)
locale to work correctly in the engine.  They are actually more than
+
{
just abbreviations; they tell the parser how to incrementally parse
+
SWMgr library(new MarkupFilterMgr(FMT_PLAIN));
versekey text.  Notice that 1 Chronicles would come, alphabetically
+
SWModule *target;
before 1 Corinthians.  The above entries say: book 46 (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.
 
  
IMPORTANT:
+
if (argc != 3) {
 +
fprintf(stderr, "\nusage: %s <modname> <\"lookup key\">\n"
 +
"\tExample: lookup KJV \"James 1:19\"\n\n", argv[0]);
 +
exit(-1);
 +
}
  
1) There MUST be at least 1 abbreviation entry for each book name
+
target = library.getModule(argv[1]);
comprised of a toupper (uppercase function) of the entire string
+
if (!target) {
EXACTLY as you have translated it in the [Text] section.
+
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);
 +
}
  
2) The English abbreviation entries MUST remain in the locale.
+
target->setKey(argv[2]);
The precedence entries may be tweaked, especially if you find them
 
interfering with your precedence entries, but the entire book name--
 
as stated in the first requirement above, must remain for English book
 
names.
 
  
Following are the REQUIRED entries from our excerpt book names above.
+
target->RenderText();    // force an entry lookup first to resolve key to something pretty for printing below.
  
GENESIS=1
+
std::cout << target->getKeyText() << ":\n";
EXODUS=2
+
std::cout << target->RenderText();
LEVITICUS=3
+
std::cout << "\n";
+
std::cout << "==========================\n";
# <snip rest of english abbrevs>
+
std::cout << std::endl;
+
return 0;
1. MOSE=1
+
}
2. MOSE=2
+
</pre>
3. MOSE=3
 
  
That's it for requirements. Tuning your locale can be important for the
+
== API Documentation ==
user experience. Many [Book Abbrevs] entries may be added to assign
+
See [http://www.crosswire.org/~ghellings/svnclassdocs/ The SWORD Project - API documentation] for the current (or very nearly current) SVN HEAD.
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).
 
  
You can test your locale with the sword/tests/parsekey test program (this
+
== See also ==
program is in the SWORD source along with several other programs that are
+
* [[Sword library versions]]
used to validate the configuration files) and try different strings to see
 
how they parse.
 
  
Notice especially that indicating a range is usually done with '-', for example Gen 1-Gen 2. Therefore the '-' character in book names will cause problems with the applications. Currently there is no solution to this. Other non-alphabetic characters are also problematic.
+
[[Category:Development tools|SWORD]]
+
[[Category:Documentation|SWORD]]
---
+
[[Category:Localization|SWORD]]
Submissions should be sent to patches@crosswire.org
+
[[Category:SWORD]]

Latest revision as of 14:00, 11 January 2018

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.

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).

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();

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.

See also