/****************************************************************************** * * swmgr.h - definition of class SWMgr used to interact with an install * base of sword modules. * * $Id: swmgr.h 3541 2017-12-03 18:40:33Z scribe $ * * Copyright 1997-2014 CrossWire Bible Society (http://www.crosswire.org) * CrossWire Bible Society * P. O. Box 2528 * Tempe, AZ 85280-2528 * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the * Free Software Foundation version 2. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * */ /** @mainpage The SWORD Project - API documentation * This is the API documentation for The SWORD Project. * It describes the structure of the SWORD library and documents the functions of the classes. * From time to time this documentation gives programming examples, too. * * SWORD provides a simple to use engine for working with many types of texts including Bibles, * commentaries, lexicons, glossaries, daily devotionals, and others. * * Some main classes: * * SWMgr gives access to an installed library of modules (books). * SWModule represents an individual module * SWKey represents a location into a module (e.g. "John 3:16") * * An API Primer can be found at: * * http://crosswire.org/sword/develop/swordapi/apiprimer.jsp * * If you're interested in working on a client which uses SWORD, please first have a look at * some of the existing ones. They can always use help, and will also prove to be good examples * if you decide to start a new project. * * Well known frontends are: * -BibleTime * -BPBible * -Eloquent * -PocketSword * -The SWORD Projectfor Windows * -Xiphos * See http://crosswire.org/applications.jsp for links to each and a more * complete list. */ #ifndef SWMGR_H #define SWMGR_H #include #include #include #include #include SWORD_NAMESPACE_START class SWModule; class SWFilter; class SWOptionFilter; class SWFilterMgr; class SWBuf; class SWKey; typedef std::map < SWBuf, SWModule *, std::less < SWBuf > >ModMap; typedef std::map < SWBuf, SWFilter * >FilterMap; typedef std::map < SWBuf, SWOptionFilter * >OptionFilterMap; typedef std::list < SWBuf >StringList; typedef std::list < SWFilter* >FilterList; typedef std::list < SWOptionFilter* >OptionFilterList; class FileDesc; class SWOptionFilter; /** SWMgr exposes an installed module set * * 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 3541 2017-12-03 18:40:33Z scribe $ */ class SWDLLEXPORT SWMgr { private: bool mgrModeMultiMod; bool augmentHome; void commonInit(SWConfig *iconfig, SWConfig *isysconfig, bool autoload, SWFilterMgr *filterMgr, bool multiMod = false); protected: SWFilterMgr *filterMgr; //made protected because because BibleTime needs it SWConfig *myconfig; //made protected because because BibleTime needs it SWConfig *mysysconfig; SWConfig *homeConfig; /** * 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; SWFilter *gbfplain; SWFilter *thmlplain; SWFilter *osisplain; SWFilter *teiplain; SWOptionFilter *transliterator; FilterList cleanupFilters; FilterMap extraFilters; StringList options; /** * 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); } /** * 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); /** * 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); /** * Deprecated. Use addStripFilters instead. */ 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); /** * 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); /** * 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); // 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 static const char *MODTYPE_BIBLES; static const char *MODTYPE_COMMENTARIES; static const char *MODTYPE_LEXDICTS; static const char *MODTYPE_GENBOOKS; static const char *MODTYPE_DAILYDEVOS; static bool isICU; static const char *globalConfPath; /** * 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 */ char *prefixPath; /** path to main module set configuration */ 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 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. * * @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 &getModules(); const ModMap &getModules() const { return const_cast(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 = 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 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 * 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 * For example, this will create an SWMgr and cause its modules to produce HTMLHREF formatted output * when asked for renderable text: * * SWMgr *myMgr = new SWMgr(0, 0, true, new MarkupFilterMgr(FMT_HTMLHREF)); */ SWMgr(SWConfig *iconfig = 0, SWConfig *isysconfig = 0, bool autoload = true, SWFilterMgr *filterMgr = 0, bool multiMod = false); /** */ SWMgr(SWFilterMgr *filterMgr, bool multiMod = false); /** * @param iConfigPath provide a custom path to use for module set location, instead of * searching the system for it. */ SWMgr(const char *iConfigPath, bool autoload = true, SWFilterMgr *filterMgr = 0, bool multiMod = false, bool augmentHome = true); /** The destructor of SWMgr. * This function cleans up the modules and deletes the created object. * Destroying the SWMgr causes all retrieved SWModule object to be invalid, so * be sure to destroy only when retrieved objects are no longer needed. */ virtual ~SWMgr(); /** * Adds books from a new path to the library * @param path the path in which to search for books * @param multiMod whether or not to keep multiple copies of the same book if found in different paths * default - false, uses last found version of the book */ virtual void augmentModules(const char *path, bool multiMod = false); void deleteModule(const char *); /** Looks for any newly installed module.conf file in the path provided, * displays the copyright information to the user, and then copies the * module.conf to the main module set's mods.d directory * @param dir where to search for new modules */ virtual void InstallScan(const char *dir); /** * 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. 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(); /** 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 * value. Well known and often used values are "Footnotes" or "Strong's Numbers" * @param value new value. Common values are "On" and "Off" */ virtual void setGlobalOption(const char *option, const char *value); /** Get the current value of the given option * @param option the name of the option, who's value is desired * @return the value of the given option */ virtual const char *getGlobalOption(const char *option); /** Gets a brief description for the given option * @param option the name of the option, who's tip is desired * @return description text * @see setGlobalOption, getGlobalOption, getGlobalOptions */ virtual const char *getGlobalOptionTip(const char *option); /** Gets a list of all available option names * @return list of option names */ virtual StringList getGlobalOptions(); /** Gets a list of legal values to which a specific option * may be set * @param option the name of the option, who's legal values are desired * @return a list of legal values for the given option */ virtual StringList getGlobalOptionValues(const char *option); /** Filters a buffer thru a named filter * @param filterName * @param text buffer to filter * @param key context key if filter needs this for processing * @param module context module if filter needs this for processing * @return error status */ virtual char filterText(const char *filterName, SWBuf &text, const SWKey *key = 0, const SWModule *module = 0); /** * Sets the cipher key for the given module. This function updates the key * at runtime, but it does not write to the config file. * 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 * 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); * * } * @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 unlock key we use for the module. */ virtual signed char setCipherKey(const char *modName, const char *key); }; SWORD_NAMESPACE_END #endif