1/*
2 Copyright 2006 Kevin Ottens <ervin@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) version 3, or any
8 later version accepted by the membership of KDE e.V. (or its
9 successor approved by the membership of KDE e.V.), which shall
10 act as a proxy defined in Section 6 of version 3 of the license.
11
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Lesser General Public License for more details.
16
17 You should have received a copy of the GNU Lesser General Public
18 License along with this library. If not, see <http://www.gnu.org/licenses/>.
19*/
20
21#ifndef SOLID_PREDICATE_H
22#define SOLID_PREDICATE_H
23
24#include <QtCore/QVariant>
25#include <QtCore/QSet>
26
27#include <solid/solid_export.h>
28
29#include <solid/deviceinterface.h>
30
31namespace Solid
32{
33 class Device;
34
35 /**
36 * This class implements predicates for devices.
37 *
38 * A predicate is a logical condition that a given device can match or not.
39 * It's a constraint about the value a property must have in a given device
40 * interface, or any combination (conjunction, disjunction) of such
41 * constraints.
42 *
43 * FIXME: Add an example.
44 */
45 class SOLID_EXPORT Predicate
46 {
47 public:
48 /**
49 * The comparison operator which can be used for matching within the predicate.
50 *
51 * - Equals, the property and the value will match for strict equality
52 * - Mask, the property and the value will match if the bitmasking is not null
53 */
54 enum ComparisonOperator { Equals, Mask };
55
56 /**
57 * The predicate type which controls how the predicate is handled
58 *
59 * - PropertyCheck, the predicate contains a comparison that needs to be matched using a ComparisonOperator
60 * - Conjunction, the two contained predicates need to be true for this predicate to be true
61 * - Disjunction, either of the two contained predicates may be true for this predicate to be true
62 * - InterfaceCheck, the device type is compared
63 */
64 enum Type { PropertyCheck, Conjunction, Disjunction, InterfaceCheck };
65
66 /**
67 * Constructs an invalid predicate.
68 */
69 Predicate();
70
71 /**
72 * Copy constructor.
73 *
74 * @param other the predicate to copy
75 */
76 Predicate(const Predicate &other);
77
78 /**
79 * Constructs a predicate matching the value of a property in
80 * a given device interface.
81 *
82 * @param ifaceType the device interface type the device must have
83 * @param property the property name of the device interface
84 * @param value the value the property must have to make the device match
85 * @param compOperator the operator to apply between the property and the value when matching
86 */
87 Predicate(const DeviceInterface::Type &ifaceType,
88 const QString &property, const QVariant &value,
89 ComparisonOperator compOperator = Equals);
90
91 /**
92 * Constructs a predicate matching the value of a property in
93 * a given device interface.
94 *
95 * @param ifaceName the name of the device interface the device must have
96 * @param property the property name of the device interface
97 * @param value the value the property must have to make the device match
98 * @param compOperator the operator to apply between the property and the value when matching
99 */
100 Predicate(const QString &ifaceName,
101 const QString &property, const QVariant &value,
102 ComparisonOperator compOperator = Equals);
103
104 /**
105 * Constructs a predicate matching devices being of a particular device interface
106 *
107 * @param ifaceType the device interface the device must have
108 */
109 explicit Predicate(const DeviceInterface::Type &ifaceType);
110
111 /**
112 * Constructs a predicate matching devices being of a particular device interface
113 *
114 * @param ifaceName the name of the device interface the device must have
115 */
116 explicit Predicate(const QString &ifaceName);
117
118 /**
119 * Destroys a Predicate object.
120 */
121 ~Predicate();
122
123
124 /**
125 * Assignement operator.
126 *
127 * @param other the predicate to assign
128 * @return this predicate after having assigned 'other' to it
129 */
130 Predicate &operator=(const Predicate &other);
131
132
133 /**
134 * 'And' operator.
135 *
136 * @param other the second operand
137 * @return a new 'and' predicate having 'this' and 'other' as operands
138 */
139 Predicate operator &(const Predicate &other);
140
141 /**
142 * 'AndEquals' operator.
143 *
144 * @param other the second operand
145 * @return assigns to 'this' a new 'and' predicate having 'this' and 'other' as operands
146 */
147 Predicate &operator &=(const Predicate &other);
148
149 /**
150 * 'Or' operator.
151 *
152 * @param other the second operand
153 * @return a new 'or' predicate having 'this' and 'other' as operands
154 */
155 Predicate operator|(const Predicate &other);
156
157 /**
158 * 'OrEquals' operator.
159 *
160 * @param other the second operand
161 * @return assigns to 'this' a new 'or' predicate having 'this' and 'other' as operands
162 */
163 Predicate &operator|=(const Predicate &other);
164
165 /**
166 * Indicates if the predicate is valid.
167 *
168 * Predicate() is the only invalid predicate.
169 *
170 * @return true if the predicate is valid, false otherwise
171 */
172 bool isValid() const;
173
174 /**
175 * Checks if a device matches the predicate.
176 *
177 * @param device the device to match against the predicate
178 * @return true if the given device matches the predicate, false otherwise
179 */
180 bool matches(const Device &device) const;
181
182 /**
183 * Retrieves the device interface types used in this predicate.
184 *
185 * @return all the device interface types used in this predicate
186 */
187 QSet<DeviceInterface::Type> usedTypes() const;
188
189 /**
190 * Converts the predicate to its string form.
191 *
192 * @return a string representation of the predicate
193 */
194 QString toString() const;
195
196 /**
197 * Converts a string to a predicate.
198 *
199 * @param predicate the string to convert
200 * @return a new valid predicate if the given string is syntactically
201 * correct, Predicate() otherwise
202 */
203 static Predicate fromString(const QString &predicate);
204
205 /**
206 * Retrieves the predicate type, used to determine how to handle the predicate
207 *
208 * @since 4.4
209 * @return the predicate type
210 */
211 Type type() const;
212
213 /**
214 * Retrieves the interface type.
215 *
216 * @note This is only valid for InterfaceCheck and PropertyCheck types
217 * @since 4.4
218 * @return a device interface type used by the predicate
219 */
220 DeviceInterface::Type interfaceType() const;
221
222 /**
223 * Retrieves the property name used when retrieving the value to compare against
224 *
225 * @note This is only valid for the PropertyCheck type
226 * @since 4.4
227 * @return a property name
228 */
229 QString propertyName() const;
230
231 /**
232 * Retrieves the value used when comparing a devices property to see if it matches the predicate
233 *
234 * @note This is only valid for the PropertyCheck type
235 * @since 4.4
236 * @return the value used
237 */
238 QVariant matchingValue() const;
239
240 /**
241 * Retrieves the comparison operator used to compare a property's value
242 *
243 * @since 4.4
244 * @note This is only valid for Conjunction and Disjunction types
245 * @return the comparison operator used
246 */
247 ComparisonOperator comparisonOperator() const;
248
249 /**
250 * A smaller, inner predicate which is the first to appear and is compared with the second one
251 *
252 * @since 4.4
253 * @note This is only valid for Conjunction and Disjunction types
254 * @return The predicate used for the first operand
255 */
256 Predicate firstOperand() const;
257
258 /**
259 * A smaller, inner predicate which is the second to appear and is compared with the first one
260 *
261 * @since 4.4
262 * @note This is only valid for Conjunction and Disjunction types
263 * @return The predicate used for the second operand
264 */
265 Predicate secondOperand() const;
266
267 private:
268 class Private;
269 Private * const d;
270 };
271}
272
273#endif
274