Mailcommon

searchpattern.h
1 /*
2 
3  SPDX-FileCopyrightText: Marc Mutz <[email protected]>
4 
5  SPDX-License-Identifier: GPL-2.0-or-later
6 */
7 
8 #pragma once
9 
10 #include "mailcommon/searchrule.h"
11 #include "mailcommon_export.h"
12 #include <KLocalizedString>
13 
14 #include <QList>
15 #include <QString>
16 
17 #include <Akonadi/SearchQuery>
18 
19 namespace Akonadi
20 {
21 class Item;
22 }
23 
24 namespace KMime
25 {
26 class Message;
27 }
28 
29 class KConfigGroup;
30 
31 namespace MailCommon
32 {
33 // Needed for MSVC 2010, as it seems to not implicit cast for a pointer anymore
34 #ifdef _MSC_VER
35 uint qHash(SearchRule::Ptr sr);
36 #endif
37 
38 // ------------------------------------------------------------------------
39 
40 /** This class is an abstraction of a search over messages. It is
41  intended to be used inside a KFilter (which adds KFilterAction's),
42  as well as in KMSearch. It can read and write itself into a
43  KConfig group and there is a constructor, mainly used by KMFilter
44  to initialize from a preset KConfig-Group.
45 
46  From a class hierarchy point of view, it is a QPtrList of
47  SearchRule's that adds the boolean operators (see Operator)
48  'and' and 'or' that connect the rules logically, and has a name
49  under which it could be stored in the config file.
50 
51  As a QPtrList with autoDelete enabled, it assumes that it is the
52  central repository for the rules it contains. So if you want to
53  reuse a rule in another pattern, make a deep copy of that rule.
54 
55  @short An abstraction of a search over messages.
56  @author Marc Mutz <[email protected]>
57 */
58 class MAILCOMMON_EXPORT SearchPattern : public QList<SearchRule::Ptr>
59 {
60 public:
61  /**
62  * Boolean operators that connect the return values of the
63  * individual rules. A pattern with @p OpAnd will match iff all
64  * it's rules match, whereas a pattern with @p OpOr will match if
65  * any of it's rules matches.
66  */
67  enum Operator {
68  OpAnd,
69  OpOr,
70  OpAll,
71  };
72 
73  enum SparqlQueryError {
74  NoError = 0,
75  MissingCheck,
76  FolderEmptyOrNotIndexed,
77  EmptyResult,
78  NotEnoughCharacters,
79  };
80 
81  /**
82  * Constructor which provides a pattern with minimal, but
83  * sufficient initialization. Unmodified, such a pattern will fail
84  * to match any KMime::Message. You can query for such an empty
85  * rule by using isEmpty, which is inherited from QPtrList.
86  */
87  SearchPattern();
88 
89  /**
90  * Constructor that initializes from a given KConfig group, if
91  * given. This feature is mainly (solely?) used in KMFilter,
92  * as we don't allow to store search patterns in the config (yet).
93  */
94  explicit SearchPattern(const KConfigGroup &config);
95 
96  /** Destructor. Deletes all stored rules! */
97  ~SearchPattern();
98 
99  /**
100  * The central function of this class. Tries to match the set of
101  * rules against a KMime::Message. It's virtual to allow derived
102  * classes with added rules to reimplement it, yet reimplemented
103  * methods should and (&&) the result of this function with their
104  * own result or else most functionality is lacking, or has to be
105  * reimplemented, since the rules are private to this class.
106  *
107  * @return true if the match was successful, false otherwise.
108  */
109  bool matches(const Akonadi::Item &item, bool ignoreBody = false) const;
110 
111  /**
112  * Returns the required part from the item that is needed for the search to
113  * operate. See @ref SearchRule::RequiredPart */
114  SearchRule::RequiredPart requiredPart() const;
115 
116  /**
117  * Removes all empty rules from the list. You should call this
118  * method whenever the user had had control of the rules outside of
119  * this class. (e.g. after editing it with SearchPatternEdit).
120  */
121  QString purify(bool removeAction = true);
122 
123  /**
124  * Reads a search pattern from a KConfigGroup. If it does not find
125  * a valid saerch pattern in the preset group, initializes the pattern
126  * as if it were constructed using the default constructor.
127  *
128  * For backwards compatibility with previous versions of KMail, it
129  * checks for old-style filter rules (e.g. using @p OpIgnore)
130  * in @p config und converts them to the new format on writeConfig.
131  *
132  * Derived classes reimplementing readConfig() should also call this
133  * method, or else the rules will not be loaded.
134  */
135  void readConfig(const KConfigGroup &config);
136 
137  /**
138  * Writes itself into @p config. Tries to delete old-style keys by
139  * overwriting them with QString().
140  *
141  * Derived classes reimplementing writeConfig() should also call this
142  * method, or else the rules will not be stored.
143  */
144  void writeConfig(KConfigGroup &config) const;
145 
146  /**
147  * Returns the name of the search pattern.
148  */
149  QString name() const
150  {
151  return mName;
152  }
153 
154  /**
155  * Sets the name of the search pattern. KMFilter uses this to
156  * store it's own name, too.
157  */
158  void setName(const QString &newName)
159  {
160  mName = newName;
161  }
162 
163  /**
164  * Returns the filter operator.
165  */
167  {
168  return mOperator;
169  }
170 
171  /**
172  * Sets the filter operator.
173  */
175  {
176  mOperator = aOp;
177  }
178 
179  static int filterRulesMaximumSize();
180  /**
181  * Returns the pattern as string. For debugging.
182  */
183  QString asString() const;
184 
185  /**
186  * Returns the pattern as akonadi query
187  */
188  SparqlQueryError asAkonadiQuery(Akonadi::SearchQuery &) const;
189 
190  /**
191  * Overloaded assignment operator. Makes a deep copy.
192  */
193  const SearchPattern &operator=(const SearchPattern &aPattern);
194 
195  /**
196  * Writes the pattern into a byte array for persistence purposes.
197  */
198  QByteArray serialize() const;
199 
200  /**
201  * Constructs the pattern from a byte array serialization.
202  */
203  void deserialize(const QByteArray &);
204 
207 
208  void generateSieveScript(QStringList &requiresModules, QString &code);
209 
210 private:
211  /**
212  * Tries to import a legacy search pattern, ie. one that still has
213  * e.g. the @p unless or @p ignore operator which were useful as long as
214  * the number of rules was restricted to two. This method is called from
215  * readConfig, which detects legacy configurations and also makes sure
216  * that this method is called from an initialized object.
217  */
218  MAILCOMMON_NO_EXPORT void importLegacyConfig(const KConfigGroup &config);
219 
220  /**
221  * Initializes the object. Clears the list of rules, sets the name
222  * to "<i18n("unnamed")>", and the boolean operator to @p OpAnd.
223  */
224  void init();
225  QString mName;
226  Operator mOperator;
227 };
228 }
229 
230 Q_DECLARE_METATYPE(MailCommon::SearchRule::RequiredPart)
std::shared_ptr< SearchRule > Ptr
Defines a pointer to a search rule.
Definition: searchrule.h:29
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Operator
Boolean operators that connect the return values of the individual rules.
Definition: searchpattern.h:67
KCALENDARCORE_EXPORT QDataStream & operator>>(QDataStream &in, const KCalendarCore::Alarm::Ptr &)
RequiredPart
Possible required parts.
Definition: searchrule.h:68
SearchPattern::Operator op() const
Returns the filter operator.
KCALENDARCORE_EXPORT uint qHash(const KCalendarCore::Period &key)
void setOp(SearchPattern::Operator aOp)
Sets the filter operator.
void setName(const QString &newName)
Sets the name of the search pattern.
This class is an abstraction of a search over messages.
Definition: searchpattern.h:58
QString name() const
Returns the name of the search pattern.
The filter dialog.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 03:59:52 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.