---
name: "swmodule"
section: "3"
platform: "linux"
package: "libsword-dev"
version: "1.5.3-3woody2"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/swmodule"
---

# swmodule(3)

The class SWModule is the base class for all modules used in Sword.

## NAME

SWModule - The class SWModule is the base class for all modules used in Sword.

## SYNOPSIS

`#include <swmodule.h>`

Inherited by **SWCom**, **SWLD**, and **SWText**.

### Public Methods

**SWModule** (const char \*imodname=0, const char \*imoddesc=0, **SWDisplay** \*idisp=0, char \*imodtype=0, bool unicode=false)\
 *Initializes data for instance of SWModule.* virtual **~SWModule** ()\
 *Cleans up instance of SWModule.* virtual char **Error** ()\
 *Gets and clears error status.* virtual const bool **isUnicode** () const\
 virtual const int **getEntrySize** () const\
 virtual char **SetKey** (const **SWKey** \*ikey)\
 *Sets a key to this module for position to a particular record or set of records.* virtual char **SetKey** (const **SWKey** &ikey)\
 *Sets the key of this module.* virtual **SWKey**& **Key** () const\
 *Gets the current module key.* virtual char **Key** (const **SWKey** &ikey)\
 *Sets the current key of the module to ikey, and returns the keytext.* virtual const char\* **KeyText** (const char \*imodtype=0)\
 *Sets/gets module KeyText.* virtual char **Display** ()\
 *Calls this modules display object and passes itself.* virtual **SWDisplay**\* **Disp** (**SWDisplay** \*idisp=0)\
 *Sets/gets display driver.* virtual char\* **Name** (const char \*imodname=0)\
 *Sets/gets module name.* virtual char\* **Description** (const char \*imoddesc=0)\
 *Sets/gets module description.* virtual char\* **Type** (const char \*imodtype=0)\
 *Sets/gets module type.* virtual **ListKey**& **Search** (const char \*istr, int searchType=0, int flags=0, **SWKey** \*scope=0, bool \*justCheckIfSupported=0, void(\*percent)(char, void \*)=&nullPercent, void \*percentUserData=0)\
 *Searches a module for a string.* virtual char **createSearchFramework** ()\
 virtual bool **hasSearchFramework** ()\
 virtual bool **isSearchOptimallySupported** (const char \*istr, int searchType, int flags, **SWKey** \*scope)\
 virtual **SWKey**\* **CreateKey** ()\
 *Allocates a key of specific type for module.* virtual **operator char \*** ()\
 *Renders and returns the current module text.* virtual char\* **getRawEntry** ()=0\
 *This function is reimplemented by the different kinds of module objects.* virtual **operator SWKey &** ()\
 virtual **operator SWKey \*** ()\
 virtual bool **isWritable** ()\
 *Is the module writable? :).* virtual SWModule& **operator\<\<** (const char \*)\
 *Modify the current module entry text only if module* **isWritable**. virtual SWModule& **operator\<\<** (const **SWKey** \*)\
 *Link the current module entry to another module entry only if module* **isWritable**. virtual void **deleteEntry** ()\
 *Delete current module entry - only if module* **isWritable**. virtual SWModule& **operator-=** (int decrement)\
 *Decrements module key a number of entries.* virtual SWModule& **operator+=** (int increment)\
 *Increments module key a number of entries.* virtual SWModule& **operator++** (int)\
 *Increments module key by 1 entry.* virtual SWModule& **operator--** (int)\
 *Decrements module key by 1 entry.* virtual SWModule& **operator=** (SW\_POSITION p)\
 *Positions this modules to an entry.* virtual SWModule& **AddRenderFilter** (**SWFilter** \*newfilter)\
 *Adds a RenderFilter to this module's.* virtual SWModule& **RemoveRenderFilter** (**SWFilter** \*oldfilter)\
 *Removes a RenderFilter to this module's.* virtual void **renderFilter** (char \*buf, long size, **SWKey** \***key**)\
 *RenderFilter a text buffer.* virtual SWModule& **AddStripFilter** (**SWFilter** \*newfilter)\
 *Adds a StripFilter to this module's stripfilters queue.* virtual void **stripFilter** (char \*buf, long size, **SWKey** \***key**)\
 *StripFilter a text buffer.* virtual SWModule& **AddRawFilter** (**SWFilter** \*newfilter)\
 *Adds a RawFilter to this module's rawfilters queue.* virtual void **filterBuffer** (FilterList \*filters, char \*buf, long size, **SWKey** \***key**)\
 *FilterBuffer a text buffer.* virtual void **rawFilter** (char \*buf, long size, **SWKey** \***key**)\
 *RawFilter a text buffer.* virtual SWModule& **AddOptionFilter** (**SWFilter** \*newfilter)\
 *Adds an OptionFilter to this module's optionfilters queue.* virtual void **optionFilter** (char \*buf, long size, **SWKey** \***key**)\
 *OptionFilter a text buffer.* virtual const char\* **StripText** (char \*buf=0, int len=-1)\
 *calls all StripFilters on buffer or current text.* virtual const char\* **RenderText** (char \*buf=0, int len=-1)\
 *calls all RenderFilters on buffer or current text.* virtual const char\* **StripText** (**SWKey** \*tmpKey)\
 *calls all StripFilters on current text.* virtual const char\* **RenderText** (**SWKey** \*tmpKey)\
 *calls all RenderFilters on current text.*

### Public Attributes

bool **terminateSearch**\
 *Set this bool to false to terminate the search which is executed by this module (***Search**).

### Static Public Methods

void **nullPercent** (char percent, void \*userData)\
 *This is the default callback function for searching.* char **createModule** (const char \*)\
 *Creates a new module.*

### Protected Attributes

char **error**\
 **SWKey**\* **key**\
 *the current key.* **ListKey** **listkey**\
 char\* **modname**\
 char\* **moddesc**\
 char\* **modtype**\
 **SWDisplay**\* **disp**\
 *this module's display object.* char\* **entrybuf**\
 FilterList\* **stripFilters**\
 *executed to remove all markup (for searches).* FilterList\* **rawFilters**\
 *executed immediately upon fileread.* FilterList\* **renderFilters**\
 *executed to format for display.* FilterList\* **optionFilters**\
 *executed to change markup to user prefs.* bool **render**\
 bool **unicode**\
 int **entrySize**\

### Static Protected Attributes

**SWDisplay** **rawdisp**\

## DETAILED DESCRIPTION

The class SWModule is the base class for all modules used in Sword.

Definition at line 47 of file swmodule.h.

## CONSTRUCTOR & DESTRUCTOR DOCUMENTATION

### SWModule::SWModule (const char \* imodname = 0, const char \* imoddesc = 0, SWDisplay \* idisp = 0, char \* imodtype = 0, bool unicode = false)

Initializes data for instance of SWModule.

**Parameters:**

- *imodname*

  Internal name for module; see also **Name**

- *imoddesc*

  Name to display to user for module; see also **Description**

- *idisp*

  Display object to use for displaying see also **Disp**

- *imodtype*

  Type of Module (All modules will be displayed with others of same type under their modtype heading) see also **Type**

## MEMBER FUNCTION DOCUMENTATION

### SWModule & SWModule::AddOptionFilter (SWFilter \* newfilter)` [inline, virtual]`

Adds an OptionFilter to this module's optionfilters queue.

**Parameters:**

- *newfilter*

  the filter to add

**Returns:**  \*this

Definition at line 443 of file swmodule.h.

### SWModule & SWModule::AddRawFilter (SWFilter \* newfilter)` [inline, virtual]`

Adds a RawFilter to this module's rawfilters queue.

**Parameters:**

- *newfilter*

  the filter to add

**Returns:**  \*this

Definition at line 410 of file swmodule.h.

### SWModule & SWModule::AddRenderFilter (SWFilter \* newfilter)` [inline, virtual]`

Adds a RenderFilter to this module's.

**See also:**  renderfilters queue

**Parameters:**

- *newfilter*

  the filter to add

**Returns:**  \*this

Definition at line 363 of file swmodule.h.

### SWModule & SWModule::AddStripFilter (SWFilter \* newfilter)` [inline, virtual]`

Adds a StripFilter to this module's stripfilters queue.

**Parameters:**

- *newfilter*

  the filter to add

**Returns:**  \*this

Definition at line 391 of file swmodule.h.

### SWKey \* SWModule::CreateKey ()` [virtual]`

Allocates a key of specific type for module.

**Returns:**  pointer to allocated key

Reimplemented in **SWCom**, **SWLD**, and **SWText**.

### char \* SWModule::Description (const char \* imoddesc = 0)` [virtual]`

Sets/gets module description.

**Parameters:**

- *imoddesc*

  value which to set moddesc; \[0\] - only get

**Returns:**  pointer to moddesc

### SWDisplay \* SWModule::Disp (SWDisplay \* idisp = 0)` [virtual]`

Sets/gets display driver.

**Parameters:**

- *idisp*

  value which to set disp; \[0\] - only get

**Returns:**  pointer to disp

### char SWModule::Display ()` [virtual]`

Calls this modules display object and passes itself.

**Returns:**  error status

### char SWModule::Error ()` [virtual]`

Gets and clears error status.

**Returns:**  error status

### char SWModule::Key (const SWKey & ikey)` [inline, virtual]`

Sets the current key of the module to ikey, and returns the keytext.

**Parameters:**

- *ikey*

  new current key for the module

**Returns:**  the keytext of the current module key

Definition at line 161 of file swmodule.h.

### SWKey & SWModule::Key () const` [inline, virtual]`

Gets the current module key.

**Returns:**  the current key of this module

Definition at line 151 of file swmodule.h.

### const char \* SWModule::KeyText (const char \* ikeytext = 0)` [virtual]`

Sets/gets module KeyText.

**Parameters:**

- *ikeytext*

  value which to set keytext; \[0\] - only get

**Returns:**  pointer to keytext

Reimplemented in **SWLD**.

### char \* SWModule::Name (const char \* imodname = 0)` [virtual]`

Sets/gets module name.

**Parameters:**

- *imodname*

  value which to set modname; \[0\] - only get

**Returns:**  pointer to modname

### SWModule & SWModule::RemoveRenderFilter (SWFilter \* oldfilter)` [inline, virtual]`

Removes a RenderFilter to this module's.

**See also:**  renderfilters queue

**Parameters:**

- *oldfilter*

  the filter to remove

**Returns:**  \*this

Definition at line 372 of file swmodule.h.

### const char \* SWModule::RenderText (SWKey \* tmpKey)` [virtual]`

calls all RenderFilters on current text.

**Parameters:**

- *tmpKey*

  key to use to grab text

**Returns:**  this module's text at specified key location massaged by Render filters

### const char \* SWModule::RenderText (char \* buf = 0, int len = -1)` [virtual]`

calls all RenderFilters on buffer or current text.

**Parameters:**

- *buf*

  buffer to Render instead of current module position; if buf is NULL, the current text will be used

- *len*

  max len of buf OR current text -- will be applied anyway

**Returns:**  this module's text at specified key location massaged by Render filters

### ListKey & SWModule::Search (const char \* istr, int searchType = 0, int flags = 0, SWKey \* scope = 0, bool \* justCheckIfSupported = 0, void(\* percent)(char, void \*) = &nullPercent, void \* percentUserData = 0)` [virtual]`

Searches a module for a string.

**Parameters:**

- *istr*

  string for which to search

- *searchType*

  type of search to perform \>=0 -\>regex; 1-\>phrase; 2-\>multiword;

- *flags*

  options flags for search

- *justCheckIfSupported*

  if set, don't search, only tell if this function supports requested search.

**Returns:**  listkey set to verses that contain istr

### char SWModule::SetKey (const SWKey & ikey)` [virtual]`

Sets the key of this module.

Similair to

**See also:**  **SetKey**(const SWKey\*) .

**Parameters:**

- *ikey*

  The **SWKey** which should be used as new key.

**Returns:**  Error status

### char SWModule::SetKey (const SWKey \* ikey)` [virtual]`

Sets a key to this module for position to a particular record or set of records.

**Parameters:**

- *ikey*

  key with which to set this module

**Returns:**  error status

Referenced by Key().

### const char \* SWModule::StripText (SWKey \* tmpKey)` [virtual]`

calls all StripFilters on current text.

**Parameters:**

- *tmpKey*

  key to use to grab text

**Returns:**  this module's text at specified key location massaged by Strip filters

### const char \* SWModule::StripText (char \* buf = 0, int len = -1)` [virtual]`

calls all StripFilters on buffer or current text.

**Parameters:**

- *buf*

  buf to massage instead of current module position; if buf is NULL, the current text will be used

- *len*

  max len of buf OR current text -- will be applied anyway

**Returns:**  this module's text at specified key location massaged by Strip filters

### char \* SWModule::Type (const char \* imodtype = 0)` [virtual]`

Sets/gets module type.

**Parameters:**

- *imodtype*

  value which to set modtype; \[0\] - only get

**Returns:**  pointer to modtype

### char SWModule::createModule (const char \* path)` [inline, static]`

Creates a new module.

**Parameters:**

- *path*

  The first parameter is path of the new module

**Returns:**  error

Definition at line 296 of file swmodule.h.

### void SWModule::filterBuffer (FilterList \* filters, char \* buf, long size, SWKey \* key)` [inline, virtual]`

FilterBuffer a text buffer.

**Parameters:**

- *filters*

  the FilterList of filters to iterate

- *buf*

  the buffer to filter

- *size*

  the allocated size of the buffer

- *key*

  key location from where this buffer was extracted

**Returns:**  \*this

Definition at line 422 of file swmodule.h.

Referenced by optionFilter(), rawFilter(), renderFilter(), and stripFilter().

### const int SWModule::getEntrySize () const` [inline, virtual]`

**Returns:**  The size of the current entry.

Definition at line 130 of file swmodule.h.

### char \* SWModule::getRawEntry ()` [pure virtual]`

This function is reimplemented by the different kinds of module objects.

**Returns:**  the raw module text of the current entry

### const bool SWModule::isUnicode () const` [inline, virtual]`

**Returns:**  True if this module is encoded in Unicode, otherwise return false.

Definition at line 126 of file swmodule.h.

### bool SWModule::isWritable ()` [inline, virtual]`

Is the module writable? :).

**Returns:**  yes or no

Definition at line 288 of file swmodule.h.

### void SWModule::nullPercent (char percent, void \* userData)` [static]`

This is the default callback function for searching.

This function is a placeholder and does nothing. You can define your own function for search progress evaluation, and pass it over to **Search**.

### SWModule::operator char \* ()` [virtual]`

Renders and returns the current module text.

**Returns:**  the rendered current module text

### SWModule & SWModule::operator+= (int increment)` [virtual]`

Increments module key a number of entries.

**Parameters:**

- *increment*

  Number of entries to jump forward

**Returns:**  \*this

### SWModule & SWModule::operator-= (int decrement)` [virtual]`

Decrements module key a number of entries.

**Parameters:**

- *decrement*

  Number of entries to jump backward

**Returns:**  \*this

### SWModule & SWModule::operator\<\< (const SWKey \* linkKey)` [inline, virtual]`

Link the current module entry to another module entry only if module **isWritable**.

- **Returns:**

  \*this

Definition at line 312 of file swmodule.h.

### SWModule & SWModule::operator\<\< (const char \* inbuf)` [inline, virtual]`

Modify the current module entry text only if module **isWritable**.

- **Returns:**

  \*this

Definition at line 304 of file swmodule.h.

### SWModule & SWModule::operator= (SW\_POSITION pos)` [virtual]`

Positions this modules to an entry.

**Parameters:**

- *p*

  position (e.g. TOP, BOTTOM)

**Returns:**  \*this

### void SWModule::optionFilter (char \* buf, long size, SWKey \* key)` [inline, virtual]`

OptionFilter a text buffer.

**Parameters:**

- *buf*

  the buffer to filter

- *size*

  the allocated size of the buffer

- *key*

  key location from where this buffer was extracted

**Returns:**  \*this

Definition at line 454 of file swmodule.h.

### void SWModule::rawFilter (char \* buf, long size, SWKey \* key)` [inline, virtual]`

RawFilter a text buffer.

**Parameters:**

- *buf*

  the buffer to filter

- *size*

  the allocated size of the buffer

- *key*

  key location from where this buffer was extracted

**Returns:**  \*this

Definition at line 435 of file swmodule.h.

### void SWModule::renderFilter (char \* buf, long size, SWKey \* key)` [inline, virtual]`

RenderFilter a text buffer.

**Parameters:**

- *buf*

  the buffer to filter

- *size*

  the allocated size of the buffer

- *key*

  key location from where this buffer was extracted

**Returns:**  \*this

Definition at line 383 of file swmodule.h.

### void SWModule::stripFilter (char \* buf, long size, SWKey \* key)` [inline, virtual]`

StripFilter a text buffer.

**Parameters:**

- *buf*

  the buffer to filter

- *size*

  the allocated size of the buffer

- *key*

  key location from where this buffer was extracted

**Returns:**  \*this

Definition at line 402 of file swmodule.h.

## MEMBER DATA DOCUMENTATION

### bool SWModule::terminateSearch

Set this bool to false to terminate the search which is executed by this module (**Search**).

This is useful for threaded applications to terminate the search in another thread.

Definition at line 97 of file swmodule.h.

## AUTHOR

Generated automatically by Doxygen for The Sword Project from the source code.