File indexing completed on 2024-12-01 03:29:23

0001 /*
0002     This file is part of Kiten, a KDE Japanese Reference Tool
0003     SPDX-FileCopyrightText: 2001 Jason Katz-Brown <jason@katzbrown.com>
0004     SPDX-FileCopyrightText: 2006 Joseph Kerian <jkerian@gmail.com>
0005     SPDX-FileCopyrightText: 2006 Eric Kjeldergaard <kjelderg@gmail.com>
0006     SPDX-FileCopyrightText: 2011 Daniel E. Moctezuma <democtezuma@gmail.com>
0007 
0008     SPDX-License-Identifier: LGPL-2.0-or-later
0009 */
0010 
0011 #ifndef KITEN_ENTRY_H
0012 #define KITEN_ENTRY_H
0013 
0014 #include <QHash>
0015 #include <QStringList>
0016 
0017 #include "kiten_export.h"
0018 
0019 #include "dictquery.h"
0020 
0021 class Entry;
0022 class EntryList;
0023 class QString;
0024 
0025 /**
0026  * The Entry class is a generic base class for each particular entry in a given dictionary.
0027  * It's used as the basic class to ferry information back to the user application.
0028  * It also handles some of the display aspects.
0029  */
0030 class KITEN_EXPORT Entry
0031 {
0032     friend class EntryListModel;
0033 
0034 private:
0035     /**
0036      * Default constructor, should not be used. Made private to serve as a warning
0037      * that you're doing something wrong if you try to call this.
0038      */
0039     Entry();
0040 
0041 protected:
0042     /**
0043      * Copy constructor
0044      */
0045     Entry(const Entry &);
0046     /**
0047      * Constructor that includes the dictionary source. This does not need to be overridden by
0048      * subclasses, but you might find it to be convenient as the superclass constructor to call
0049      * from your constructors.
0050      * @param sourceDictionary the dictionary name (not fileName) that this entry originated with
0051      */
0052     Entry(const QString &sourceDictionary);
0053     /**
0054      * A constructor that includes the basic information, nicely separated
0055      * @param sourceDictionary the dictionary name (not fileName) that this entry originated with
0056      * @param word the word entry of this dictionary entry (normally kanji/kana)
0057      * @param readings a list of possible pronunciations for this result (kana)
0058      * @param meanings a list of possible meanings for this word
0059      */
0060     Entry(const QString &sourceDictionary, const QString &word, const QStringList &readings, const QStringList &meanings);
0061 
0062 public:
0063     /**
0064      * Generic Destructor
0065      */
0066     virtual ~Entry() = default;
0067     /**
0068      * A clone method, this should just implement "return new EntrySubClass(*this)"
0069      */
0070     virtual Entry *clone() const = 0;
0071 
0072     /**
0073      * Fairly important method, this tests if this particular entry matches a query. The
0074      * EDICT and Kanjidic doSearch methods do an approximate match, load an Entry, and then
0075      * check more carefully by calling this method. This works nicely for handling searchWithinResults
0076      * cleanly.
0077      */
0078     virtual bool matchesQuery(const DictQuery &) const;
0079 
0080     /**
0081      * Get the dictionary name that generated this Entry. I can't think of a reason to be changing this
0082      */
0083     QString getDictName() const;
0084     /**
0085      * Get the dictionary type (e.g. edict, kanjidic).
0086      */
0087     virtual QString getDictionaryType() const = 0;
0088     /**
0089      * Get the word from this Entry. If the entry is of type kanji/kana/meaning/etc, this will
0090      * return the kanji. If it is of kana/meaning/etc, it will return kana.
0091      */
0092     QString getWord() const;
0093     /**
0094      * Get a QString containing all of the meanings known, connected by the outputListDelimiter
0095      */
0096     QString getMeanings() const;
0097     /**
0098      * Simple accessor
0099      */
0100     QStringList getMeaningsList() const;
0101     /**
0102      * Simple accessor
0103      */
0104     QString getReadings() const;
0105     /**
0106      * Simple accessor
0107      */
0108     QStringList getReadingsList() const;
0109     /**
0110      * Simple accessor
0111      */
0112     QHash<QString, QString> getExtendedInfo() const;
0113     /**
0114      * Simple accessor
0115      * @param x the key for the extended info item to get
0116      */
0117     QString getExtendedInfoItem(const QString &x) const;
0118     /**
0119      * Simple accessor
0120      * @param key the key for the extended item that is being verified
0121      * @param value the value it is supposed to have
0122      * @returns true if the key has that value, false if it is different or does not exist
0123      */
0124     virtual bool extendedItemCheck(const QString &key, const QString &value) const;
0125 
0126     /**
0127      * An entry should be able to generate a representation of itself in (valid) HTML
0128      */
0129     virtual QString toHTML() const;
0130     /**
0131      * KVTML format for exporting
0132      */
0133     virtual QString toKVTML() const;
0134     /**
0135      * This will return a pure text interpretation of the Entry
0136      */
0137     virtual QString toString() const;
0138 
0139     /**
0140      * An entry should be able to parse an in-file representation of an entry
0141      * as a QString and put it back.  The latter will be useful for writing
0142      * to dictionaries on disk at some point.
0143      */
0144     virtual bool loadEntry(const QString &) = 0;
0145     /**
0146      * Return a QString of an entry, as if it were dumped back into it's source file
0147      */
0148     virtual QString dumpEntry() const = 0;
0149 
0150     /**
0151      * An overrideable sorting function, similar to operator< in most contexts
0152      * The default version will sort by dictionary, then by fields
0153      *
0154      * @param that the second item we are comparing (this) with
0155      * @param dictOrder the list of dictionaries (in order) to sort
0156      *               If this list is empty, the entries will not be sorted in order
0157      * @param fields the list of fields to sort in, uses special codes of
0158      *              Reading, Meaning, Word/Kanji for those elements, all others by their
0159      *              extended attribute keys.
0160      */
0161     virtual bool sort(const Entry &that, const QStringList &dictOrder, const QStringList &fields) const;
0162     /**
0163      * Overrideable sorting mechanism for sorting by individual fields.
0164      * The sort routine checks if the given field is equal, before calling this virtual function
0165      * So if this is called, you can assume that this->extendedItem(field) != that.extendedItem(field)
0166      *
0167      * @param that the second item we are comparing (this) with
0168      * @param field the specific extended item field that is being compared
0169      */
0170     virtual bool sortByField(const Entry &that, const QString &field) const;
0171 
0172 protected:
0173     /**
0174      * The Word (usually containing kanji) that matches this entry. If you override the accessors
0175      * above, this has no use.
0176      */
0177     QString Word;
0178     /**
0179      * The Meanings that match this entry. If you override the accessors
0180      * above, this has no use.
0181      */
0182     QStringList Meanings;
0183     /**
0184      * The Readings (usually kana) that match this entry. If you override the accessors
0185      * above, this has no use.
0186      */
0187     QStringList Readings;
0188     /**
0189      * A hash of extended information. You may find it useful to store all sorts of details here
0190      */
0191     QHash<QString, QString> ExtendedInfo;
0192 
0193     /**
0194      * The dictionary that this entry originated at
0195      */
0196     QString sourceDict;
0197     /**
0198      * The delimiter for lists... usually space
0199      */
0200     QString outputListDelimiter;
0201 
0202     /**
0203      * This is used by the constructors to set some default values
0204      */
0205     void init();
0206 
0207     /**
0208      * Handy function for generating a link from a given QString
0209      */
0210     virtual QString makeLink(const QString &entryString) const;
0211     /**
0212      * Return and HTML version of a word
0213      */
0214     virtual QString HTMLWord() const;
0215     /**
0216      * Return and HTML version of a reading list
0217      */
0218     virtual QString HTMLReadings() const;
0219     /**
0220      * Return and HTML version of a meaning list
0221      */
0222     virtual QString HTMLMeanings() const;
0223 
0224     /**
0225      * Handy Utility functions for matching to lists and identifying char types
0226      */
0227     bool listMatch(const QStringList &list, const QStringList &test, DictQuery::MatchType type) const;
0228     /**
0229      * Handy Utility functions for matching to lists and identifying char types
0230      */
0231     bool isKanji(const QChar &character) const;
0232 };
0233 
0234 #endif