Solid::Predicate Class
class Solid::Predicate| Header: | #include <Predicate> |
| CMake: | find_package(KF6 REQUIRED COMPONENTS Solid)target_link_libraries(mytarget PRIVATE KF6::Solid) |
Public Types
| enum | ComparisonOperator { Equals, Mask } |
| enum | Type { PropertyCheck, Conjunction, Disjunction, InterfaceCheck } |
Public Functions
| Predicate() | |
| Predicate(const QString &ifaceName) | |
| Predicate(const Solid::DeviceInterface::Type &ifaceType) | |
| Predicate(const QString &ifaceName, const QString &property, const QVariant &value, Solid::Predicate::ComparisonOperator compOperator = Equals) | |
| Predicate(const Solid::DeviceInterface::Type &ifaceType, const QString &property, const QVariant &value, Solid::Predicate::ComparisonOperator compOperator = Equals) | |
| Predicate(const Solid::Predicate &other) | |
| ~Predicate() | |
| Solid::Predicate::ComparisonOperator | comparisonOperator() const |
| Solid::Predicate | firstOperand() const |
| Solid::DeviceInterface::Type | interfaceType() const |
| bool | isValid() const |
| bool | matches(const Solid::Device &device) const |
| QVariant | matchingValue() const |
| QString | propertyName() const |
| Solid::Predicate | secondOperand() const |
| QString | toString() const |
| Solid::Predicate::Type | type() const |
| QSet<Solid::DeviceInterface::Type> | usedTypes() const |
| Solid::Predicate | operator&(const Solid::Predicate &other) |
| Solid::Predicate & | operator&=(const Solid::Predicate &other) |
| Solid::Predicate & | operator=(const Solid::Predicate &other) |
| Solid::Predicate | operator|(const Solid::Predicate &other) |
| Solid::Predicate & | operator|=(const Solid::Predicate &other) |
Static Public Members
| Solid::Predicate | fromString(const QString &predicate) |
Detailed Description
@class Solid::Predicate predicate.h <Solid/Predicate>
This class implements predicates for devices.
A predicate is a logical condition that a given device can match or not. It's a constraint about the value a property must have in a given device interface, or any combination (conjunction, disjunction) of such constraints.
A predicate can be: - a single comparison, or - a conjunction ("AND") of exactly two predicates, or - a disjunction ("OR") of exactly two predicates.
Since these can be nested, it is possible to express "a StorageVolume that is not ignored AND that StorageVolume contains a FileSystem AND that StorageVolume is removable". Since conjunctions use exactly two predicates (and this expression has three), square brackets are used to group the nested predicates when writing them out in full:
``` [ [ StorageVolume.ignored == false AND StorageVolume.usage == 'FileSystem' ] AND StorageVolume.removable == true ] ```
Predicates can be constructed programmatically by creating single comparisons with the Predicate constructor, and then building conjunctions with `operator&` and disjunctions with `operator|`.
Predicates can be constructed from a string by calling `fromString()` which parses the given string and returns a predicate. If there are any errors in parsing the string, an empty predicate is returned; use `isValid()` to detect whether that is the case.
The string language is described exactly in `predicate_parser.y`, but boils down to:
- a single comparison is written as `<interface>.<property> == <value>` - a single bitmask check is written as `<interface>.<property> & <value>` - a conjunction is written as `[ <predicate> AND <predicate> ]` - a disjunction is written as `[ <predicate> OR <predicate> ]`
Note the mandatory use of `[` and `]` around conjunctions and disjunctions.
Member Type Documentation
enum Predicate::ComparisonOperator
The comparison operator which can be used for matching within the predicate.
- Equals, the property and the value will match for strict equality - Mask, the property and the value will match if the bitmasking is not null
enum Predicate::Type
The predicate type which controls how the predicate is handled
- PropertyCheck, the predicate contains a comparison that needs to be matched using a ComparisonOperator - Conjunction, the two contained predicates need to be true for this predicate to be true - Disjunction, either of the two contained predicates may be true for this predicate to be true - InterfaceCheck, the device type is compared
Member Function Documentation
Predicate::Predicate()
Constructs an invalid predicate.
[explicit] Predicate::Predicate(const QString &ifaceName)
Constructs a predicate matching devices being of a particular device interface
@param ifaceName the name of the device interface the device must have
[explicit] Predicate::Predicate(const Solid::DeviceInterface::Type &ifaceType)
Constructs a predicate matching devices being of a particular device interface
@param ifaceType the device interface the device must have
Predicate::Predicate(const QString &ifaceName, const QString &property, const QVariant &value, Solid::Predicate::ComparisonOperator compOperator = Equals)
Constructs a predicate matching the value of a property in a given device interface.
@param ifaceName the name of the device interface the device must have @param property the property name of the device interface @param value the value the property must have to make the device match @param compOperator the operator to apply between the property and the value when matching
Predicate::Predicate(const Solid::DeviceInterface::Type &ifaceType, const QString &property, const QVariant &value, Solid::Predicate::ComparisonOperator compOperator = Equals)
Constructs a predicate matching the value of a property in a given device interface.
@param ifaceType the device interface type the device must have @param property the property name of the device interface @param value the value the property must have to make the device match @param compOperator the operator to apply between the property and the value when matching
Predicate::Predicate(const Solid::Predicate &other)
Copy constructor.
@param other the predicate to copy
[noexcept] Predicate::~Predicate()
Destroys a Predicate object.
Solid::Predicate::ComparisonOperator Predicate::comparisonOperator() const
Retrieves the comparison operator used to compare a property's value
@since 4.4 @note This is only valid for Conjunction and Disjunction types @return the comparison operator used
Solid::Predicate Predicate::firstOperand() const
A smaller, inner predicate which is the first to appear and is compared with the second one
@since 4.4 @note This is only valid for Conjunction and Disjunction types @return The predicate used for the first operand
[static] Solid::Predicate Predicate::fromString(const QString &predicate)
Converts a string to a predicate.
@param predicate the string to convert @return a new valid predicate if the given string is syntactically correct, Predicate() otherwise
Solid::DeviceInterface::Type Predicate::interfaceType() const
Retrieves the interface type.
@note This is only valid for InterfaceCheck and PropertyCheck types @since 4.4 @return a device interface type used by the predicate
bool Predicate::isValid() const
Indicates if the predicate is valid.
Predicate() is the only invalid predicate.
@return true if the predicate is valid, false otherwise
bool Predicate::matches(const Solid::Device &device) const
Checks if a device matches the predicate.
@param device the device to match against the predicate @return true if the given device matches the predicate, false otherwise
QVariant Predicate::matchingValue() const
Retrieves the value used when comparing a devices property to see if it matches the predicate
@note This is only valid for the PropertyCheck type @since 4.4 @return the value used
QString Predicate::propertyName() const
Retrieves the property name used when retrieving the value to compare against
@note This is only valid for the PropertyCheck type @since 4.4 @return a property name
Solid::Predicate Predicate::secondOperand() const
A smaller, inner predicate which is the second to appear and is compared with the first one
@since 4.4 @note This is only valid for Conjunction and Disjunction types @return The predicate used for the second operand
QString Predicate::toString() const
Converts the predicate to its string form.
@return a string representation of the predicate
Solid::Predicate::Type Predicate::type() const
Retrieves the predicate type, used to determine how to handle the predicate
@since 4.4 @return the predicate type
QSet<Solid::DeviceInterface::Type> Predicate::usedTypes() const
Retrieves the device interface types used in this predicate.
@return all the device interface types used in this predicate
Solid::Predicate Predicate::operator&(const Solid::Predicate &other)
'And' operator.
@param other the second operand @return a new 'and' predicate having 'this' and 'other' as operands
Solid::Predicate &Predicate::operator&=(const Solid::Predicate &other)
'AndEquals' operator.
@param other the second operand @return assigns to 'this' a new 'and' predicate having 'this' and 'other' as operands
Solid::Predicate &Predicate::operator=(const Solid::Predicate &other)
Assignment operator.
@param other the predicate to assign @return this predicate after having assigned 'other' to it
Solid::Predicate Predicate::operator|(const Solid::Predicate &other)
'Or' operator.
@param other the second operand @return a new 'or' predicate having 'this' and 'other' as operands
Solid::Predicate &Predicate::operator|=(const Solid::Predicate &other)
'OrEquals' operator.
@param other the second operand @return assigns to 'this' a new 'or' predicate having 'this' and 'other' as operands