Difference between revisions of "DevTools:SWORD"

From CrossWire Bible Society
Jump to: navigation, search
m (Reverted edits by AceleRorsi (Talk); changed back to last version by CoricErlet)
(See also: Category:SWORD)
 
(32 intermediate revisions by 8 users not shown)
Line 1: Line 1:
boczeld
+
== Documentation ==
= Documentation =
 
  
== Locale file layout ==
+
=== 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''
  
Locales require a few things. Let's step through the German locale:
+
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.
  
excerpts from /sword/locales/de.conf:
+
=== SWModule / SWKey / SWFilter ===
  
[Meta]
+
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.
Name=de
 
Description=German
 
  
The above information is used to define the locale.  They should be
+
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:
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]
+
  RawText webster("modules/texts/rawtext/webster/", "Webster", "Webster Text");
  Genesis=1. Mose
+
  webster.setKey("jas 1:19");
  Exodus=2. Mose
+
  cout << webster->RenderText();
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
+
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.
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: 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:
+
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.
  
1) There MUST be at least 1 abbreviation entry for each book name
+
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
comprised of a toupper (uppercase function) of the entire string
+
subsequently setting multiple modules to this SWKey using calls to their .setKey() method. Example:
EXACTLY as you have translated it in the [Text] section.
 
  
2) The English abbreviation entries MUST remain in the locale.
+
RawText webster("modules/texts/rawtext/webster/", "Webster", "Webster Text");
The precedence entries may be tweaked, especially if you find them
+
RawCom mhc("modules/comments/rawcom/mhc/", "MHC", "Matthew Henry's Commentary on the Whole Bible");
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.
+
VerseKey mykey;
  
  GENESIS=1
+
  mykey.Persist(true);
EXODUS=2
 
LEVITICUS=3
 
 
# <snip rest of english abbrevs>
 
 
1. MOSE=1
 
2. MOSE=2
 
3. MOSE=3
 
  
That's it for requirementsTuning your locale can be important for the
+
webster.setKey(mykey);
user experience. Many [Book Abbrevs] entries may be added to assign
+
  mhc.setKey(mykey);
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
+
for (mykey = "jas 1:1"; mykey.Chapter() == 1; mykey++) {
program is in the sword source along with several other programs that are
+
cout << webster.getKeyText() << ":\n";
used to validate the configuration files) and try different strings to see
+
cout << (const char *) webster << "\n";
how they parse.
+
cout << "-------------\n";
 +
cout << (const char *) mhc << "\n";
 +
}
  
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. Also other non-alphabetic characters are problematic.
+
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++) {
Submissions should be sent to patches@crosswire.org
+
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:
 +
 
 +
<pre>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();</pre>
 +
 
 +
=== 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:
 +
 
 +
<pre>
 +
#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;
 +
}
 +
</pre>
 +
 
 +
== API Documentation ==
 +
See [http://www.crosswire.org/~ghellings/svnclassdocs/ The SWORD Project - API documentation] for the current (or very nearly current) SVN HEAD.
 +
 
 +
== See also ==
 +
* [[Sword library versions]]
 +
 
 +
[[Category:Development tools|SWORD]]
 +
[[Category:Documentation|SWORD]]
 +
[[Category:Localization|SWORD]]
 +
[[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