File indexing completed on 2024-04-21 03:42:01

 /*
     This file is part of Kiten, a KDE Japanese Reference Tool
     SPDX-FileCopyrightText: 2006 Joseph Kerian <jkerian@gmail.com>
     SPDX-FileCopyrightText: 2011 Daniel E. Moctezuma <democtezuma@gmail.com>
 
     SPDX-License-Identifier: LGPL-2.0-or-later
 */
 
 #ifndef KITEN_DICTQUERY_H
 #define KITEN_DICTQUERY_H
 
 #include <QHash>
 #include <QHashIterator>
 #include <QString>
 #include <QStringList>
 
 class QChar;
 
 #include "kiten_export.h"
 
 /**
  * @short A class to allow users of libkiten to properly setup a database
  * query.
  *
  * In general, you either pass or parse in parameters from users or automated
  * programs to be later sent to the dictionary manager.
  *
  * This class is one of the three critical classes (along with
  * dictionary and EntryList) that are needed to use libkiten. Essentially...
  * you feed the dictionary class a DictQuery, and dictionary will return an
  * EntryList that matches the query.
  *
  * @code
  * dictionary dictManager();
  * //Load some dictionaries via dictionary class methods
  * EntryList *results;
  * DictQuery myQuery("kanji");
  * results = dictManager.doSearch(myQuery);
  * //Print results (if any)
  * @endcode
  *
  * The internal implementation understands four distinct types of data:
  * Japanese Kanji
  * Japanese Kana
  * English Characters
  * Property Pairs of the form \<i\>name\</i\>:\<i\>value\</i\>
  *
  * It is left up to the individual dictionary types to parse these values
  * for matching and appropriateness to each dictionary.
  * You can use the setDictionaries() method to narrow the range of the
  * dictionaries that it will apply to.
  *
  * A DictQuery object can be considered an "unordered set" of values.
  * When testing for equality or comparison, each property or text entry above
  * is seen as a unique item in a set. Order is not important for these
  * operations. The object will attempt to preserve the order from parsed
  * strings, but it does not consider this order to be important.
  *
  * In general, application level programs are expected to use the
  * QString based interfaces, and dictionary implementations and other
  * parts of libkiten are expected to use the direct accessors and mutators,
  * although specialized interfaces (such as kitenradselect) may use property
  * mutators for a limited set of properties. (in this case, radicals)
  *
  * The query string input is of the following format:
  * &lt;QS&gt; ::= &lt;M&gt;DictQuery::mainDelimiter&lt;QS&gt;|&lt;R&gt;DictQuery::mainDelimiter&lt;QS&gt;|
  *       &lt;O&gt;DictQuery::mainDelimiter&lt;QS&gt;|NULL
  * &lt;M&gt;  ::= kana&lt;M&gt;|kana
  * &lt;R&gt;  ::= character&lt;R&gt;|character
  * &lt;O&gt;  ::= &lt;C&gt;DictQuery::propertySeparator&lt;D&gt;
  * &lt;C&gt;  ::= character&lt;C&gt;|character
  * &lt;D&gt;  ::= character&lt;D&gt;|character
  *
  * @author Joseph Kerian \<jkerian@gmail.com>
  */
 class KITEN_EXPORT DictQuery
 {
 public:
     /**
      * This is the main delimiter that the DictQuery uses when parsing strings.
      * It is set to "space" at the moment.
      */
     static const QString mainDelimiter;
     /**
      * This is the delimiter that DictQuery uses when parsing property strings
      * of the form <i>strokes:4</i>. It is set to ":" at the moment.
      */
     static const QString propertySeperator;
     /**
      * Normal constructor.
      *
      * This will create an empty query object.
      */
     DictQuery();
     /**
      * Constructor with a given QString.
      *
      * @param str the QString will be parsed as described below in operator=(const QString&)
      */
     explicit DictQuery(const QString &str);
     /**
      * Copy constructor
      *
      * @param orig the original DictQuery to be copied
      */
     DictQuery(const DictQuery &orig);
     /**
      * Destructor
      */
     ~DictQuery();
 
     /**
      * @return true if the DictQuery is completely empty
      */
     bool isEmpty() const;
     /**
      * Removes all text/entries from the DictQuery
      */
     void clear();
     /**
      * The assignment copy operator
      */
     DictQuery &operator=(const DictQuery &old);
     /**
      * The clone method
      */
     DictQuery *clone() const;
     /**
      * This returns a QString that represents the query. This may be the same
      * as the original string, but some slight changes may have occurred if you
      * have done any manipulations on the DictQuery.
      */
     const QString toString() const;
     /**
      * This is a conversion to a QString... useful in a surprising
      * number of cases.
      */
     operator QString() const;
 
     /**
      * Use this to get a list of all the property keys in the query
      */
     const QList<QString> listPropertyKeys() const;
     /**
      * Returns a given extended attribute
      */
     const QString operator[](const QString &key) const;
     /**
      * Sets a given extended attribute
      */
     QString operator[](const QString &key);
     /**
      * Get a specific property by key (is the same as using operator[] const)
      */
     QString getProperty(const QString &key) const;
     /**
      * Verify if a given DictQuery object has a search parameter of a
      * particular property.
      */
     bool hasProperty(const QString &key) const;
     /**
      * Set a particular property... this does significantly more error checking
      * than the operator[] version, and will return false if there was a
      * problem (an empty value or bad key)
      *
      * @param key the key for this entry
      * @param value the value to set this to, will overwrite the current contents of this location
      *
      * @returns false on failure
      */
     bool setProperty(const QString &key, const QString &value);
     /**
      * Remove all instances of a property.
      *
      * @returns true if the DictQuery had properties of the given type
      */
     bool removeProperty(const QString &key);
     /**
      * Returns and removes the property
      */
     QString takeProperty(const QString &key);
 
     /**
      * Returns a list of the dictionaries that this particular query
      * will target. An empty list (the default) will search all dictionaries
      * that the user has selected.
      */
     QStringList getDictionaries() const;
     /**
      * Set the list of dictionaries to search. This will be read and used
      * by the dictionary manager.
      */
     void setDictionaries(const QStringList &newDictionaries);
 
     /**
      * Accessor for the non-japanese meaning field
      */
     QString getMeaning() const;
     /**
      * Mutator for the Meaning field
      */
     bool setMeaning(const QString &newMeaning);
     /**
      * Accessor for the Pronunciation field (generally kana)
      */
     QString getPronunciation() const;
     /**
      * Mutator for the Pronunciation field
      */
     bool setPronunciation(const QString &newPronunciation);
     /**
      * Accessor for the Word/Kanji field (this is usually used for anything
      * containing kanji).
      */
     QString getWord() const;
     /**
      * Mutator for the Word/Kanji field. If what you are setting contains
      * only kana, consider using the setPronunciation instead.
      */
     bool setWord(const QString &newWord);
 
     /**
      * A simple setwise comparison of two DictQuery objects
      * Note that order is not important here... only each element
      * that is one of the DictQuery objects appears in the other.
      */
     KITEN_EXPORT friend bool operator==(const DictQuery &a, const DictQuery &b);
     /**
      * Convenient inverted override of operator==( DictQuery, DictQuery )
      */
     KITEN_EXPORT friend bool operator!=(const DictQuery &other, const DictQuery &query);
     /**
      * Set-wise strictly less than. A better way to think of this
      * might be the "subset" operator
      */
     KITEN_EXPORT friend bool operator<(const DictQuery &a, const DictQuery &b);
     /**
      * Convenient override of operator<( DictQuery, DictQuery ) and operator==
      */
     KITEN_EXPORT friend bool operator<=(const DictQuery &a, const DictQuery &b);
     /**
      * This will append the properties and other elements of the added kanji
      * onto the elements of the current element. If regenerated as a string,
      * it should look something like concatenation
      */
     DictQuery &operator+=(const DictQuery &old);
     /**
      * A simple string parser, look above for examples and explanations
      */
     DictQuery &operator=(const QString &old);
     /**
      * A simple override of operator+=( const DictQuery& )
      */
     DictQuery &operator+=(const QString &old);
     /**
      * Simple addition... similar to operator+=
      */
     KITEN_EXPORT friend DictQuery operator+(const DictQuery &a, const DictQuery &b);
 #ifndef QT_NO_CAST_ASCII
     /**
      * An ascii cast variant of the operator=
      * Only available if QT_NO_CAST_ASCII is not defined on lib compilation
      */
     DictQuery &operator=(const char *);
 #endif
 
     // Specify the type of matching
     /**
      * This enum is used to define the type of matching this query is supposed
      * to do. The names are fairly self-explanatory
      */
     enum MatchType { Exact, Beginning, Ending, Anywhere };
     /**
      * Get which match type is currently set on the DictQuery.
      */
     MatchType getMatchType() const;
     /**
      * Set a match type. If this is not called, the default is matchExact.
      */
     void setMatchType(MatchType newType);
 
     /**
      * This enum is used to define the type of matching this query is supposed
      * to do.
      */
     enum MatchWordType { Any, Verb, Noun, Adjective, Adverb, Prefix, Suffix, Expression };
     /**
      * Get which word type is currently set on the DictQuery.
      */
     MatchWordType getMatchWordType() const;
     /**
      * Set a word type. If this is not called, the default value is 'Any'.
      */
     void setMatchWordType(MatchWordType newType);
 
     enum FilterType { NoFilter, Rare, CommonUncommon };
     /**
      * Get which filter is currently set on the DictQuery.
      */
     FilterType getFilterType() const;
     /**
      * Set whether or not the query should output results separated in
      * common and uncommon sections.
      */
     void setFilterType(FilterType newType);
 
     /**
      * This enum is used as the return type for the two utility functions,
      * stringTypeCheck and charTypeCheck.
      */
     enum StringTypeEnum { Kanji, Kana, Latin, Mixed, ParseError };
     /**
      * A simple utility routine to tell us what sort of string we have
      * If the string contains only kanji, kana or non-kanji/kana characters, the result is strTypeKanji,
      * strTypeKana or strTypeLatin (perhaps a misnomer... but so far it's valid).
      * If the string contains both kanji and kana, the type returned is strTypeKanji
      * If the string contains any other combination, the return type is mixed.
      */
     static StringTypeEnum stringTypeCheck(const QString &in);
     /**
      * This utility does the same thing for QChar as stringTypeCheck does for QString. At the moment
      * the implementation is rather simple, and it assumes that anything that is not latin1 or kana is
      * a kanji.
      */
     static StringTypeEnum charTypeCheck(const QChar &ch);
 
 private:
     class Private;
     Private *const d;
 };
 
 // Currently... KDE doesn't seem to want to use exceptions
 #ifdef LIBKITEN_USING_EXCEPTIONS
 class InvalidQueryException
 {
 public:
     InvalidQueryException(QString x)
     {
         m_val = x;
     }
     InvalidQueryException(QString m = "Invalid Query String", QString x)
     {
         m_val = x;
         m_msg = m;
     }
     QString value()
     {
         return m_val;
     }
     QString message()
     {
         return m_msg;
     }
 
 protected:
     QString m_val;
     QString m_msg;
 };
 #endif
 
 #endif