[sword-devel] Why You Should Love SWORD 103 - What Is A Filters

[Troy A. Griffitts]

*The anatomy of an SWFilter*
____________________________


At the most basic level, a SWORD filter performs some distinct and
concise transformation to the data stream.

The actual signature of a filter is very minimal, and looking at the
SWFilter interface itself...

http://crosswire.org/svn/sword/trunk/include/swfilter.h

... there is simply 1 method you need to implemented to create a filter:

char SWFilter::processText(
		SWBuf		&text,
	const	SWKey		*key	= 0,
	const	SWModule	*module	= 0) = 0;


Basically, you're sent a buffer of text, possibly along with some
context in the form of an SWKey and SWModule-- in case you care, and
then you make some small change to the buffer.

Easy, right?  Well, sortof.

Anyone can write a filter.  The great thing about filters is that they
partition up a very complicated task: processing a complex document,
into tiny manageable chunks that anyone can tackle.

"Handle <title> tags in a buffer?  Sure, I can do that!  That's easy....
 Wait....  What should I _DO_ with a <title> tag?"

That's when the real world hits and things get more complex.  A SWORD
filter is an easy to grasp, easy to code against, abstract concept.

How filters are orchestrated together inside the SWORD engine-- what
distinct roles they are expected to fill, when, and in what order-- is
hidden knowledge that for years only few have been privy to yield...

Stay tuned for "The Red Pill" coming soon to a listserv near you.