Mailcommon

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

KDE's Doxygen guidelines are available online.