diff options
Diffstat (limited to 'include/swmgr.h')
-rw-r--r-- | include/swmgr.h | 326 |
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 §ion); - 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 §ion, ConfigEntMap::iterator start, ConfigEntMap::iterator end); - virtual void AddLocalOptions(SWModule *module, ConfigEntMap §ion, 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 §ion); + + /** + * 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 §ion, 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 §ion); + + /** + * Deprecated. Use addLocalOptionFilters instead. + */ + SWDEPRECATED virtual void AddLocalOptions(SWModule *module, ConfigEntMap §ion, 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 §ion); + + /** + * Deprecated. Use addEncodingFilters instead + */ + SWDEPRECATED virtual void AddEncodingFilters(SWModule *module, ConfigEntMap §ion) { 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 §ion); + virtual void addEncodingFilters(SWModule *module, ConfigEntMap §ion); /** - * 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 §ion) { 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 §ion); + virtual void addRenderFilters(SWModule *module, ConfigEntMap §ion); /** - * 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 §ion); + SWDEPRECATED virtual void AddStripFilters(SWModule *module, ConfigEntMap §ion) { 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 §ion); - // ones manually specified in .conf file - virtual void AddStripFilters(SWModule *module, ConfigEntMap §ion, ConfigEntMap::iterator start, ConfigEntMap::iterator end); + /** + * Deprecated. Use addLocalStripFilters instead. + */ + SWDEPRECATED virtual void AddStripFilters(SWModule *module, ConfigEntMap §ion, 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 §ion); /** - * 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 §ion) { 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 §ion); + virtual void addRawFilters(SWModule *module, ConfigEntMap §ion); + // 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); }; |