swmodule.h

Go to the documentation of this file.

/******************************************************************************
 *
 * swmodule.h - class SWModule: the basis for all types of modules
 *      (e.g. Bibles, commentaries, maps, lexicons, general books, etc.)
 *
 * $Id: swmodule.h 3846 2021-02-24 21:04:04Z scribe $
 *
 * Copyright 1997-2013 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.
 *
 */

#ifndef SWMODULE_H
#define SWMODULE_H

#include <swdisp.h>
#include <listkey.h>
#include <swconfig.h>

#include <swcacher.h>
#include <swsearchable.h>
#ifndef _WIN32_WCE
#include <iostream>
#endif

#include <list>

#include <defs.h>

SWORD_NAMESPACE_START


enum {DIRECTION_LTR = 0, DIRECTION_RTL, DIRECTION_BIDI};
enum {FMT_UNKNOWN = 0, FMT_PLAIN, FMT_THML, FMT_GBF, FMT_HTML, FMT_HTMLHREF, FMT_RTF, FMT_OSIS, FMT_WEBIF, FMT_TEI, FMT_XHTML, FMT_LATEX};
enum {ENC_UNKNOWN = 0, ENC_LATIN1, ENC_UTF8, ENC_SCSU, ENC_UTF16, ENC_RTF, ENC_HTML};
enum {BIB_BIBTEX = 0, /* possible future formats: BIB_MARCXML, BIB_MARC21, BIB_DCMI BIB_OSISHEADER, BIB_SBL_XHTML, BIB_MLA_XHTML, BIB_APA_XHTML, BIB_CHICAGO_XHTML */};


class SWOptionFilter;
class SWFilter;


#define SWMODULE_OPERATORS \
    operator SWBuf() { return renderText(); } \
    operator SWKey &() { return *getKey(); } \
    operator SWKey *() { return getKey(); } \
    SWModule &operator <<(const char *inbuf) { setEntry(inbuf); return *this; } \
    SWModule &operator <<(const SWKey *sourceKey) { linkEntry(sourceKey); return *this; } \
    SWModule &operator -=(int steps) { decrement(steps); return *this; } \
    SWModule &operator +=(int steps) { increment(steps); return *this; } \
    SWModule &operator ++(int) { return *this += 1; } \
    SWModule &operator --(int) { return *this -= 1; } \
    SWModule &operator =(SW_POSITION p) { setPosition(p); return *this; } \
    \
    SWDEPRECATED operator const char *() { static SWBuf unsafeTmp = renderText(); return unsafeTmp.c_str(); }


typedef std::list < SWFilter * >FilterList;
typedef std::list < SWOptionFilter * >OptionFilterList;
typedef std::map < SWBuf, SWBuf, std::less < SWBuf > > AttributeValue;
typedef std::map < SWBuf, AttributeValue, std::less < SWBuf > > AttributeList;
typedef std::map < SWBuf, AttributeList, std::less < SWBuf > > AttributeTypeList;

#define SWTextDirection char
#define SWTextEncoding char
#define SWTextMarkup char

// TODO: should all SWModule decendents be SWCachers?  Only some really
// cache data.  But if we don't do this, then we need another mechanism to
// check if we are an SWCacher.  Maybe make SWModule extend SWObject (which
// it probably should anyway.  But then we need to add all the cheezy
// heirarchy info to all the decendent classes for our SWDYNAMIC_CAST and
// then we can see if we implement SWCacher so we know whether or not to add
// to the yet to be developed cachemgr.
// Just leave for now.  This lets us always able to call module->flush()
// to manually flush a cache, and doesn't hurt if there is no work done.


class SWDLLEXPORT SWModule : public SWCacher, public SWSearchable {

private:
    class StdOutDisplay : public SWDisplay {
        char display(SWModule &imodule) {
#ifndef _WIN32_WCE
            std::cout << imodule.renderText();
#endif
            return 0;
        }
    };

protected:

    ConfigEntMap ownConfig;
    ConfigEntMap *config;
    mutable AttributeTypeList entryAttributes;
    mutable bool procEntAttr;

    mutable char error;
    bool skipConsecutiveLinks;

    SWKey *key;

    ListKey listKey;
    char *modname;
    char *moddesc;
    char *modtype;
    char *modlang;

    char direction;
    char markup;
    char encoding;

    SWDisplay *disp;

    static StdOutDisplay rawdisp;
    mutable SWBuf entryBuf;

    FilterList *stripFilters;

    FilterList *rawFilters;

    FilterList *renderFilters;

    OptionFilterList *optionFilters;

    FilterList *encodingFilters;

    mutable int entrySize;
    mutable long entryIndex;     // internal common storage for index

    static void prepText(SWBuf &buf);


public:
    // used for matching whole entry (not substring) in entry attributes searches.
    static const signed int SEARCHFLAG_MATCHWHOLEENTRY;

    // used for turning off the default behavior of SWORD to use a sliding search window 
    // which allows hits across verse boundaries.
    static const signed int SEARCHFLAG_STRICTBOUNDARIES;

    static const signed int SEARCHTYPE_REGEX;
    static const signed int SEARCHTYPE_PHRASE;
    static const signed int SEARCHTYPE_MULTIWORD;
    static const signed int SEARCHTYPE_ENTRYATTR;
    static const signed int SEARCHTYPE_EXTERNAL;

    bool terminateSearch;

    SWModule(const char *imodname = 0, const char *imoddesc = 0, SWDisplay * idisp = 0, const char *imodtype = 0, SWTextEncoding encoding = ENC_UNKNOWN, SWTextDirection dir = DIRECTION_LTR, SWTextMarkup markup = FMT_UNKNOWN, const char *modlang = 0);

    virtual ~SWModule();

    virtual char popError();
    SWDEPRECATED virtual char Error() { return popError(); }

    virtual bool isUnicode() const { return (encoding == (char)ENC_UTF8 || encoding == (char)ENC_SCSU); }

    // These methods are useful for modules that come from a standard SWORD install (most do).
    // SWMgr will call setConfig.  The user may use getConfig and getConfigEntry (if they
    // are not comfortable with, or don't wish to use  stl maps).
    virtual void setConfig(ConfigEntMap *config);
    virtual const ConfigEntMap &getConfig() const { return *config; }

    virtual const char *getConfigEntry(const char *key) const;

    virtual SWBuf getBibliography(unsigned char bibFormat = BIB_BIBTEX) const;

    virtual int getEntrySize() const { return entrySize; }

    virtual char setKey(const SWKey *ikey);

    inline char setKeyText(const char *keyText) { getKey()->setText(keyText); return key->getError(); }

    char setKey(const SWKey &ikey) { return setKey(&ikey); }

    SWDEPRECATED char SetKey(const SWKey *ikey) { return setKey(ikey); }
    SWDEPRECATED char SetKey(const SWKey &ikey) { return setKey(ikey); }
    SWDEPRECATED char Key(const SWKey & ikey) { return setKey(ikey); }

    virtual SWKey *getKey() const;
    SWDEPRECATED SWKey &Key() const { return *getKey(); }

    SWDEPRECATED const char *KeyText(const char *ikeytext = 0) { if (ikeytext) setKey(ikeytext); return *getKey(); }

    virtual const char *getKeyText() const {
        return *getKey();
    }


    virtual long getIndex() const { return entryIndex; }
    virtual void setIndex(long iindex) { entryIndex = iindex; }
    SWDEPRECATED long Index() const { return getIndex(); }
    SWDEPRECATED long Index(long iindex) { setIndex(iindex); return getIndex(); }

    virtual char display();
    SWDEPRECATED char Display() { return display(); }

    virtual SWDisplay *getDisplay() const;

    virtual void setDisplay(SWDisplay * idisp);

    SWDEPRECATED SWDisplay *Disp(SWDisplay * idisp = 0) { if (idisp)    setDisplay(idisp); return getDisplay(); }

    const char *getName() const;
    SWDEPRECATED const char *Name() const { return getName(); }

    SWDEPRECATED const char *Name(const char *imodname) { stdstr(&modname, imodname); return getName(); }

    const char *getDescription() const;
    SWDEPRECATED const char *Description() const { return getDescription(); }

    SWDEPRECATED const char *Description(const char *imoddesc) { stdstr(&moddesc, imoddesc); return getDescription(); }

    const char *getType() const;
    SWDEPRECATED const char *Type() const { return getType(); }

    void setType(const char *imodtype) { stdstr(&modtype, imodtype); }
    SWDEPRECATED const char *Type(const char *imodtype) { setType(imodtype); return getType(); }

    virtual char getDirection() const;
    SWDEPRECATED char Direction(signed char newdir = -1) { char retVal = getDirection(); if (newdir != -1) return direction = newdir; return retVal; }

    char getEncoding() const { return encoding; }
    SWDEPRECATED char Encoding(signed char enc = -1) { char retVal = getEncoding(); if (enc != -1) encoding = enc; return retVal; }

    char getMarkup() const { return markup; }
    SWDEPRECATED char Markup(signed char imarkup = -1) { char retVal = getMarkup(); if (imarkup != -1) markup = imarkup; return retVal; }

    const char *getLanguage() const { return modlang; }
    SWDEPRECATED const char *Lang(char *imodlang = 0) { if (imodlang != 0) stdstr(&modlang, imodlang); return getLanguage(); }


    // search interface -------------------------------------------------

    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);

    // for backward compat-- deprecated

    SWDEPRECATED 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) {   return search(istr, searchType, flags, scope, justCheckIfSupported, percent, percentUserData);  }


    virtual SWKey *createKey() const;
    SWDEPRECATED SWKey *CreateKey() const { return createKey(); }

    virtual SWBuf &getRawEntryBuf() const = 0;

    const char *getRawEntry() const { return getRawEntryBuf().c_str(); }

    // write interface ----------------------------
    virtual bool isWritable() const { return false; }

    static signed char createModule(const char *path);

    virtual void setEntry(const char *inbuf, long len= -1);

    virtual void linkEntry(const SWKey *sourceKey);

    virtual void deleteEntry() {}

    // end write interface ------------------------

    virtual void decrement(int steps = 1);

    virtual void increment(int steps = 1);

    virtual void setPosition(SW_POSITION pos);

    virtual void filterBuffer(OptionFilterList *filters, SWBuf &buf, const SWKey *key) const;

    virtual void filterBuffer(FilterList *filters, SWBuf &buf, const SWKey *key) const;

    virtual SWModule &addRenderFilter(SWFilter *newFilter) {
        renderFilters->push_back(newFilter);
        return *this;
    }
    SWDEPRECATED SWModule &AddRenderFilter(SWFilter *newFilter) { return addRenderFilter(newFilter); }

    virtual const FilterList &getRenderFilters() const {
        return *renderFilters;
    }

    virtual SWModule &removeRenderFilter(SWFilter *oldFilter) {
        renderFilters->remove(oldFilter);
        return *this;
    }
    SWDEPRECATED SWModule &RemoveRenderFilter(SWFilter *oldFilter) {    return removeRenderFilter(oldFilter); }

    virtual SWModule &replaceRenderFilter(SWFilter *oldFilter, SWFilter *newFilter) {
        FilterList::iterator iter;
        for (iter = renderFilters->begin(); iter != renderFilters->end(); iter++) {
            if (*iter == oldFilter)
                *iter = newFilter;
        }
        return *this;
    }
    SWDEPRECATED SWModule &ReplaceRenderFilter(SWFilter *oldFilter, SWFilter *newFilter) { return replaceRenderFilter(oldFilter, newFilter); }

    virtual void renderFilter(SWBuf &buf, const SWKey *key) const {
        filterBuffer(renderFilters, buf, key);
    }

    virtual SWModule &addEncodingFilter(SWFilter *newFilter) {
        encodingFilters->push_back(newFilter);
        return *this;
    }
    SWDEPRECATED SWModule &AddEncodingFilter(SWFilter *newFilter) { return addEncodingFilter(newFilter); }

    virtual SWModule &removeEncodingFilter(SWFilter *oldFilter) {
        encodingFilters->remove(oldFilter);
        return *this;
    }
    SWDEPRECATED SWModule &RemoveEncodingFilter(SWFilter *oldFilter) { return removeEncodingFilter(oldFilter); }

    virtual SWModule &replaceEncodingFilter(SWFilter *oldFilter, SWFilter *newFilter) {
        FilterList::iterator iter;
        for (iter = encodingFilters->begin(); iter != encodingFilters->end(); iter++) {
            if (*iter == oldFilter)
                *iter = newFilter;
        }
        return *this;
    }
    SWDEPRECATED SWModule &ReplaceEncodingFilter(SWFilter *oldFilter, SWFilter *newFilter) { return replaceEncodingFilter(oldFilter, newFilter); }

    virtual void encodingFilter(SWBuf &buf, const SWKey *key) const {
        filterBuffer(encodingFilters, buf, key);
    }

    virtual SWModule &addStripFilter(SWFilter *newFilter) {
        stripFilters->push_back(newFilter);
        return *this;
    }
    SWDEPRECATED SWModule &AddStripFilter(SWFilter *newFilter) { return addStripFilter(newFilter);  }

    virtual SWModule &addRawFilter(SWFilter *newFilter) {
        rawFilters->push_back(newFilter);
        return *this;
    }
    SWDEPRECATED SWModule &AddRawFilter(SWFilter *newFilter) { return addRawFilter(newFilter); }

    virtual void stripFilter(SWBuf &buf, const SWKey *key) const {
        filterBuffer(stripFilters, buf, key);
    }


    virtual void rawFilter(SWBuf &buf, const SWKey *key) const {
        filterBuffer(rawFilters, buf, key);
    }

    virtual SWModule &addOptionFilter(SWOptionFilter *newFilter) {
        optionFilters->push_back(newFilter);
        return *this;
    }
    SWDEPRECATED SWModule &AddOptionFilter(SWOptionFilter *newFilter) { return addOptionFilter(newFilter); }

    virtual const OptionFilterList &getOptionFilters() const { return *optionFilters; }

    virtual void optionFilter(SWBuf &buf, const SWKey *key) const {
        filterBuffer(optionFilters, buf, key);
    }

    virtual const char *stripText(const char *buf = 0, int len = -1);
    SWDEPRECATED const char *StripText(const char *buf = 0, int len = -1) { return stripText(buf, len); }

    SWBuf renderText(const char *buf, int len = -1, bool render = true) const;
     SWBuf renderText();
    SWDEPRECATED const char *RenderText(const char *buf = 0, int len = -1, bool render = true) { return renderText(buf, len, render); }

    virtual const char *getRenderHeader() const;

    virtual const char *stripText(const SWKey *tmpKey);

    SWBuf renderText(const SWKey *tmpKey);

    virtual void setSkipConsecutiveLinks(bool val) { skipConsecutiveLinks = val; }

    virtual bool isSkipConsecutiveLinks() { return skipConsecutiveLinks; }
    SWDEPRECATED bool getSkipConsecutiveLinks() { return isSkipConsecutiveLinks(); }
    
    virtual bool isLinked(const SWKey *, const SWKey *) const { return false; }
    virtual bool hasEntry(const SWKey *) const { return false; }

    virtual AttributeTypeList &getEntryAttributes() const { return entryAttributes; }

    virtual void setProcessEntryAttributes(bool val) const { procEntAttr = val; }
    SWDEPRECATED void processEntryAttributes(bool val) const { setProcessEntryAttributes(val); }

    virtual bool isProcessEntryAttributes() const { return procEntAttr; }


    // SWSearchable Interface Impl -----------------------------------------------
    virtual signed char createSearchFramework(
            void (*percent) (char, void *) = &nullPercent,
            void *percentUserData = 0);
    virtual void deleteSearchFramework();
    virtual bool hasSearchFramework();

    // OPERATORS -----------------------------------------------------------------
    SWMODULE_OPERATORS

};

SWORD_NAMESPACE_END
#endif