New upstream version 1.8.1

1 files changed, 237 insertions, 89 deletions

diff --git a/include/swmgr.h b/include/swmgr.h
index 1dad90a..9ddc4aa 100644
--- a/include/swmgr.h
+++ b/include/swmgr.h
@@ -3,7 +3,7 @@
  *  swmgr.h -	definition of class SWMgr used to interact with an install
  *		base of sword modules.
  *
- * $Id: swmgr.h 3156 2014-04-17 03:50:37Z greg.hellings $
+ * $Id: swmgr.h 3541 2017-12-03 18:40:33Z scribe $
  *
  * Copyright 1997-2014 CrossWire Bible Society (http://www.crosswire.org)
  *	CrossWire Bible Society
@@ -88,7 +88,7 @@ class SWOptionFilter;
  * SWMgr exposes an installed module set and can be asked to configure the desired
  *	markup and options which modules will produce.
  *
- * @version $Id: swmgr.h 3156 2014-04-17 03:50:37Z greg.hellings $
+ * @version $Id: swmgr.h 3541 2017-12-03 18:40:33Z scribe $
  */
 class SWDLLEXPORT SWMgr {
 private:
@@ -101,9 +101,11 @@ protected:
 	SWConfig *myconfig;		//made protected because because BibleTime needs it
 	SWConfig *mysysconfig;
 	SWConfig *homeConfig;
-	void CreateMods(bool multiMod = false);
-	virtual SWModule *createModule(const char *name, const char *driver, ConfigEntMap &section);
-	void DeleteMods();
+	/**
+	 * Deprecated. Use createAllModules instead
+	 */
+	SWDEPRECATED void CreateMods(bool multiMod = false) { createAllModules(multiMod); };
+	SWDEPRECATED void DeleteMods() { deleteAllModules(); }
 	char configType;		// 0 = file; 1 = directory
 	OptionFilterMap optionFilters;
 	FilterMap cipherFilters;
@@ -115,49 +117,152 @@ protected:
 	FilterList cleanupFilters;
 	FilterMap extraFilters;
 	StringList options;
-	virtual void init(); // use to initialize before loading modules
-	virtual char AddModToConfig(FileDesc *conffd, const char *fname);
-	virtual void loadConfigDir(const char *ipath);
-	virtual void AddGlobalOptions(SWModule *module, ConfigEntMap &section, ConfigEntMap::iterator start, ConfigEntMap::iterator end);
-	virtual void AddLocalOptions(SWModule *module, ConfigEntMap &section, ConfigEntMap::iterator start, ConfigEntMap::iterator end);
-	StringList augPaths;
+	/**
+	 * method to create all modules from configuration.
+	 *
+	 * Override to add any special processing before or after
+	 * calling SWMgr::createAllModules
+	 *
+	 * e.g., augmenting a localConfig.conf to SWMgr::config
+	 * that might store CipheyKey or Font preferences per module
+	 * before actual construction of modules
+	 *
+	 */
+	virtual void createAllModules(bool multiMod = false);
+	/**
+	 * called to delete all contructed modules.  Undoes createAllModules
+	 * override to clean anything up before or after all modules are
+	 * deleted
+	 */
+	virtual void deleteAllModules();
+
+	/**
+	 * called to create exactly one module from a config entry
+	 * override to do any extra work before or after each module
+	 * is created
+	 */
+	virtual SWModule *createModule(const char *name, const char *driver, ConfigEntMap &section);
+
+	/**
+	 * call by every constructor to initialize SWMgr object
+	 * override to include any addition common initialization
+	 */
+	virtual void init();
 
+
+	/**
+	 * Deprecated.  Use addGlobalOptionFilters instead.
+	 */
+	SWDEPRECATED virtual void AddGlobalOptions(SWModule *module, ConfigEntMap &section, ConfigEntMap::iterator start, ConfigEntMap::iterator end) { addGlobalOptionFilters(module, section); }
+	/**
+	 * Adds appropriate global option filters to a module.  Override to add any special
+	 *	global option filters. Global option filters typically update SourceType markup
+	 *	to turn on and off specific features of a text when a user has optionally chosen
+	 *	to show or hide that feature, e.g. Strongs, Footnotes, Headings, etc.
+	 *	Global options can also have more than On and Off values, but these are the most
+	 *	common.
+	 *	A set of all global options included from an entire library of installed modules
+	 *	can be obtained from getGlobalOptions and presented to the user.  Values to
+	 *	which each global option may be set can be obtain from getGlobalOptionValues,
+	 *	and similar.  See that family of methods for more information.
+	 * See the module.conf GlobalOptionFilter= entries.
+	 * @param module module to which to add encoding filters
+	 * @param section configuration information for module
+	 */
+	virtual void addGlobalOptionFilters(SWModule *module, ConfigEntMap &section);
+
+	/**
+	 * Deprecated.  Use addLocalOptionFilters instead.
+	 */
+	SWDEPRECATED virtual void AddLocalOptions(SWModule *module, ConfigEntMap &section, ConfigEntMap::iterator start, ConfigEntMap::iterator end) { addLocalOptionFilters(module, section); }
+	/**
+	 * Adds appropriate local option filters to a module.  Override to add any special
+	 *	local option filters.  Local options are similar to global options in that
+	 *	they may be toggled on or off or set to some value from a range of choices
+	 *	but local option
+	 * See the module.conf LocalOptionFilter= entries.
+	 * @param module module to which to add encoding filters
+	 * @param section configuration information for module
+	 */
+	virtual void addLocalOptionFilters(SWModule *module, ConfigEntMap &section);
+
+	/**
+	 * Deprecated.  Use addEncodingFilters instead
+	 */
+	SWDEPRECATED virtual void AddEncodingFilters(SWModule *module, ConfigEntMap &section) { addEncodingFilters(module, section); }
 	/**
-	 * Called to add appropriate Encoding Filters to a module.  Override to do special actions,
-	 *	if desired.	See the module.conf Encoding= entry.
-	 * @param module module to which to add Encoding Filters
-	 * @param section configuration information from module.conf
+	 * Adds appropriate encoding filters to a module.  Override to add any special
+	 *	encoding filters.
+	 * See the module.conf Encoding= entry.
+	 * @param module module to which to add encoding filters
+	 * @param section configuration information for module
 	 */
-	virtual void AddEncodingFilters(SWModule *module, ConfigEntMap &section);
+	virtual void addEncodingFilters(SWModule *module, ConfigEntMap &section);
 
 	/**
-	 * Called to add appropriate Render Filters to a module.  Override to do special actions,
-	 *	if desired.	See the module.conf SourceType= entry.
-	 * @param module module to which to add Render Filters
-	 * @param section configuration information from module.conf
+	 * Deprecated.  Use addRenderFilters instead.
+	 */
+	SWDEPRECATED virtual void AddRenderFilters(SWModule *module, ConfigEntMap &section) { addRenderFilters(module, section); }
+	/**
+	 * Add appropriate render filters to a module.  Override to add any special
+	 *	render filters. Render filters are used for preparing a text for
+	 *	display and typically convert markup from SourceType
+	 *	to desired display markup.
+	 * See the module.conf SourceType= entry.
+	 * @param module module to which to add render filters
+	 * @param section configuration information for module
 	 */
-	virtual void AddRenderFilters(SWModule *module, ConfigEntMap &section);
+	virtual void addRenderFilters(SWModule *module, ConfigEntMap &section);
 
 	/**
-	 * Called to add appropriate Strip Filters to a module.  Override to do special actions,
-	 *	if desired.	See the module.conf SourceType= entry.
-	 * @param module module to which to add Strip Filters
-	 * @param section configuration information from module.conf
+	 * Deprecated.  Use addStripFilters instead.
 	 */
-	virtual void AddStripFilters(SWModule *module, ConfigEntMap &section);
+	SWDEPRECATED virtual void AddStripFilters(SWModule *module, ConfigEntMap &section) { addStripFilters(module, section); }
+	/**
+	 * Adds appropriate strip filters to a module.  Override to add any special
+	 *	strip filters. Strip filters are used for preparing text for searching
+	 *	and typically strip out all markup and leave only searchable words
+	 * See the module.conf SourceType= entry.
+	 * @param module module to which to add strip filters
+	 * @param section configuration information for module
+	 */
+	virtual void addStripFilters(SWModule *module, ConfigEntMap &section);
 
-	// ones manually specified in .conf file
-	virtual void AddStripFilters(SWModule *module, ConfigEntMap &section, ConfigEntMap::iterator start, ConfigEntMap::iterator end);
+	/**
+	 * Deprecated.  Use addLocalStripFilters instead.
+	 */
+	SWDEPRECATED virtual void AddStripFilters(SWModule *module, ConfigEntMap &section, ConfigEntMap::iterator start, ConfigEntMap::iterator end) { addLocalStripFilters(module, section); }
+	/**
+	 * Adds manually specified strip filters specified in module configuration
+	 * as LocalStripFilters.  These might take care of special cases of preparation
+	 * for searching, e.g., removing ()[] and underdot symbols from manuscript modules
+	 * @param module module to which to add local strip filters
+	 * @param section configuration information for module
+	 */
+	virtual void addLocalStripFilters(SWModule *module, ConfigEntMap &section);
 
 	/**
-	 * Called to add appropriate Raw Filters to a module.  Override to do special actions,
-	 *	if desired.	See the module.conf CipherKey= entry.
-	 * @param module module to which to add Raw Filters
-	 * @param section configuration information from module.conf
+	 * Deprecated.  Use addRawFilters instead.
+	 */
+	SWDEPRECATED virtual void AddRawFilters(SWModule *module, ConfigEntMap &section) { addRawFilters(module, section); }
+	/**
+	 * Add appropriate raw filters to a module.  Override to add any special
+	 *	raw filters.  Raw filters are used to manipulate a buffer
+	 *	immediately after it has been read from storage.  For example,
+	 *	any decryption that might need to be done.
+	 * See the module.conf CipherKey= entry.
+	 * @param module module to which to add raw filters
+	 * @param section configuration information for module
 	 */
-	virtual void AddRawFilters(SWModule *module, ConfigEntMap &section);
+	virtual void addRawFilters(SWModule *module, ConfigEntMap &section);
 
 
+	// still to be normalized below ...
+	//
+	StringList augPaths;
+	virtual char AddModToConfig(FileDesc *conffd, const char *fname);
+	virtual void loadConfigDir(const char *ipath);
+
 public:
 
 	// constants which represent module types used in SWModule::getType
@@ -170,14 +275,32 @@ public:
 
 	static bool isICU;
 	static const char *globalConfPath;
-	static SWBuf getHomeDir();
 
 	/**
-	 *
+	 * Deprecated.  Used FileMgr::getSystemFileMgr()->getHomeDir() instead.
+	 */
+	SWDEPRECATED static SWBuf getHomeDir();
+
+	/**
+	 * Perform all the logic to discover a SWORD configuration and libraries on a system
 	 */
 	static void findConfig(char *configType, char **prefixPath, char **configPath, StringList *augPaths = 0, SWConfig **providedSysConf = 0);
 
+	/**
+	 * The configuration of a loaded library of SWORD modules
+	 * e.g., from /usr/share/sword/mods.d/
+	 * 	augmented with ~/.sword/mods.d/
+	 * 
+	 * This represents all discovered modules and their configuration
+	 * compiled into a single SWConfig object with each [section]
+	 * representing each module. e.g. [KJV]
+	 */
 	SWConfig *config;
+
+	/**
+	 * The configuration file for SWORD
+	 * e.g., /etc/sword.conf
+	 */
 	SWConfig *sysConfig;
 
 	/** The path to main module set and locales
@@ -188,45 +311,52 @@ public:
 	 */
 	char *configPath;
 
+
+	/**
+	 * Deprecated.  Use getModules instead.
+	 */
+	ModMap Modules;
 	/** The map of available modules.
 	 *	This map exposes the installed modules.
-	 *	Here's an example how to iterate over the map and check the module type of each module.
 	 *
-	 *@code
-	 * ModMap::iterator it;
-	 * SWModule *curMod = 0;
+	 *	Here's an example how to iterate over all
+	 *	the installed modules and check the module name
+	 *	and type of each module and do something special
+	 *	if the module type is a Bible.
 	 *
-	 * for (it = Modules.begin(); it != Modules.end(); it++) {
-	 *      curMod = (*it).second;
-	 *      if (!strcmp(curMod->Type(), "Biblical Texts")) {
-	 *           // do something with curMod
-	 *      }
-	 *      else if (!strcmp(curMod->Type(), "Commentaries")) {
-	 *           // do something with curMod
-	 *      }
-	 *      else if (!strcmp(curMod->Type(), "Lexicons / Dictionaries")) {
-	 *           // do something with curMod
-	 *      }
+	 * @code
+	 *
+	 * for (ModMap::iterator it = getModules().begin(); it != getModules().end(); ++it) {
+	 *
+	 * 	SWBuf modName = it->first;
+	 * 	SWModule *mod = it->second;
+	 *
+	 * 	SWBuf modType = mod->getType();
+	 *
+	 * 	if (modType == SWMgr::MODTYPE_BIBLES) {
+	 * 		// do something with mod
+	 * 	}
 	 * }
 	 * @endcode
 	 */
-	ModMap Modules;
+	ModMap &getModules();
+	const ModMap &getModules() const { return const_cast<SWMgr *>(this)->getModules(); }
 
 	/** Gets a specific module by name.  e.g. SWModule *kjv = myManager.getModule("KJV");
 	 * @param modName the name of the module to retrieve
 	 * @return the module, if found, otherwise 0
 	 */
-	SWModule *getModule(const char *modName) { ModMap::iterator it = Modules.find(modName); return ((it != Modules.end()) ? it->second : 0); }
-	const SWModule *getModule(const char *modName) const { ModMap::const_iterator it = Modules.find(modName); return ((it != Modules.end()) ? it->second : 0); }
+	SWModule *getModule(const char *modName) { ModMap::iterator it = getModules().find(modName); return ((it != getModules().end()) ? it->second : 0); }
+	const SWModule *getModule(const char *modName) const { ModMap::const_iterator it = getModules().find(modName); return ((it != getModules().end()) ? it->second : 0); }
 
 
 	/** Constructs an instance of SWMgr
 	 *
 	 * @param iconfig manually supply a configuration.  If not supplied, SWMgr will look on the system
 	 *	using a complex hierarchical search.  See README for detailed specifics.
-	 * @param isysconfig
+	 * @param isysconfig manually supply a an isysconfig (e.g. /etc/sword.conf)
 	 * @param autoload whether or not to immediately load modules on construction of this SWMgr.
-	 *	If you reimplemented SWMgr you can set this to false and call SWMgr::Load() after you have
+	 *	If you reimplemented SWMgr you can set this to false and call SWMgr::load() after you have
 	 *	completed the contruction and setup of your SWMgr subclass.
 	 * @param filterMgr an SWFilterMgr subclass to use to manager filters on modules
 	 *	SWMgr TAKES OWNERSHIP FOR DELETING THIS OBJECT
@@ -271,12 +401,20 @@ public:
 	 */
 	virtual void InstallScan(const char *dir);
 
-	/** Load all modules.  Should only be manually called if SWMgr was constructed
+	/**
+	 * Deprecated.  Use load
+	 */
+	SWDEPRECATED virtual signed char Load() { return load(); }
+	/** Loads installed library of SWORD modules.
+	 * Should only be manually called if SWMgr was constructed
 	 *	without autoload; otherwise, this will be called on SWMgr construction
 	 * Reimplement this function to supply special functionality when modules are
-	 * initially loaded.
+	 * initially loaded. This includes
+	 * discovery of config path with SWMgr::fileconfig,
+	 * loading of composite SWMgr::config,
+	 * and construction of all modules from config using SWMgr::createAllModules
 	 */
-	virtual signed char Load();
+	virtual signed char load();
 
 	/** Change the values of global options (e.g. Footnotes, Strong's Number, etc.)
 	 * @param option The name of the option, for which you want to change the
@@ -322,43 +460,53 @@ public:
 	/**
 	 * Sets the cipher key for the given module. This function updates the key
 	 * at runtime, but it does not write to the config file.
-	 * To write the new unlock key to the config file use code like this:
+	 * This method is NOT the recommended means for applying a CipherKey
+	 * to a module.
+	 *
+	 * Typically CipherKey entries and other per module user configuration
+	 * settings are all saved in a separate localConfig.conf that is updated
+	 * by a UI or other client of the library. e.g.,
+	 *
+	 *
+	 * [KJV]
+	 * Font=Arial
+	 * LocalOptionFilter=SomeSpecialFilterMyUIAppliesToTheKJV
+	 *
+	 * [ISV]
+	 * CipherKey=xyzzy
+	 *
+	 * [StrongsGreek]
+	 * SomeUISetting=false
+	 *
+	 *
+	 * Then these extra config settings in this separate file are applied
+	 * just before module creation by overriding SWMgr::createAllModules and
+	 * augmenting SWMgr::config with code like this:
 	 *
 	 * @code
-	 * SectionMap::iterator section;
-	 * ConfigEntMap::iterator entry;
-	 * DIR *dir = opendir(configPath);
-	 * struct dirent *ent;
-	 * char* modFile;
-	 * if (dir) {    // find and update .conf file
-	 *   rewinddir(dir);
-	 *   while ((ent = readdir(dir)))
-	 *   {
-	 *     if ((strcmp(ent->d_name, ".")) && (strcmp(ent->d_name, "..")))
-	 *     {
-	 *       modFile = m_backend->configPath;
-	 *       modFile += "/";
-	 *       modFile += ent->d_name;
-	 *       SWConfig *myConfig = new SWConfig( modFile );
-	 *       section = myConfig->Sections.find( m_module->Name() );
-	 *       if ( section != myConfig->Sections.end() )
-	 *       {
-	 *         entry = section->second.find("CipherKey");
-	 *         if (entry != section->second.end())
-	 *         {
-	 *           entry->second = unlockKey;//set cipher key
-	 *           myConfig->Save();//save config file
-	 *         }
-	 *       }
-	 *       delete myConfig;
-	 *     }
-	 *   }
+	 * void createAllModules(bool multiMod) {
+	 *
+	 * 	// after SWMgr::config is loaded
+	 *	// see if we have our own local settings
+	 * 	SWBuf myExtraConf = "~/.myapp/localConf.conf";
+	 * 	bool exists = FileMgr::existsFile(extraConf);
+	 * 	if (exists) {
+	 * 		SWConfig addConfig(extraConf);
+	 * 		this->config->augment(addConfig);
+	 * 	}
+	 *
+	 * 	// now that we've augmented SWMgr::config with our own custom
+	 * 	// settings, proceed on with creating modules
+	 *
+	 * 	SWMgr::createAllModules(multiMod);
+	 *
 	 * }
-	 * closedir(dir);
 	 * @endcode
 	 *
+	 * The above convention is preferred to using this setCipherKey method
+	 *
 	 * @param modName For this module we change the unlockKey
-	 * @param key This is the new unlck key we use for te module.
+	 * @param key This is the new unlock key we use for the module.
 	 */
 	virtual signed char setCipherKey(const char *modName, const char *key);
 };