Phosphor
Qt6 / Wayland library suite for window-management tools
Loading...
Searching...
No Matches
PhosphorRules::MatchExpression Class Reference

A composable predicate tree evaluated against a WindowQuery. More...

#include <PhosphorRules/MatchExpression.h>

Classes

struct  Predicate
 Leaf predicate payload. More...

Public Types

enum class  Kind { Leaf , All , Any , None }
 Tree node kind. More...

Public Member Functions

 MatchExpression ()
 Default-constructs an empty All{} — the always-true catch-all.
Kind kind () const
bool isLeaf () const
const Predicate & predicate () const
 Leaf accessor — only meaningful when isLeaf().
const QList< MatchExpression > & children () const
 Composite accessor — empty for a leaf.
bool isCatchAll () const
 True if this is the empty catch-all All{} — matches every query.
bool isContextOnly () const
 True if this expression references only context fields (ScreenId / VirtualDesktop / Activity / Mode / TiledWindowCount) — i.e.
bool referencesAnyField (const QSet< Field > &fields) const
 True if any leaf predicate anywhere in the tree (including inside none{} negations) tests one of fields.
bool negatesAnyField (const QSet< Field > &fields) const
 True if a leaf predicate on one of fields appears anywhere INSIDE a none{} negation (at any nesting depth).
bool evaluate (const WindowQuery &query) const
 Evaluate this expression against query.
bool isValid () const
 True if this expression is structurally well-formed: every leaf has a field/operator combination that can actually match (a string operator on a numeric field is rejected), and Regex patterns compile.
QJsonObject toJson () const
bool operator== (const MatchExpression &other) const
bool operator!= (const MatchExpression &other) const

Static Public Member Functions

static MatchExpression makeLeaf (const Predicate &predicate)
 Constructs a leaf predicate expression.
static MatchExpression makeLeaf (Field field, Operator op, const QVariant &value)
static MatchExpression makeAll (const QList< MatchExpression > &children)
 Constructs a composite expression.
static MatchExpression makeAny (const QList< MatchExpression > &children)
static MatchExpression makeNone (const QList< MatchExpression > &children)
static std::optional< MatchExpression > fromJson (const QJsonObject &obj)
 Strict loader — returns nullopt on a malformed / invalid expression.

Static Public Attributes

static constexpr int kMaxParseDepth = 32
 Hard cap on the JSON parser's recursion depth.

Detailed Description

A composable predicate tree evaluated against a WindowQuery.

An expression is either:

  • a leaf — a Predicate { field, op, value }, or
  • a composite — All (AND), Any (OR), or None (NOT-any) over a list of child expressions.

MatchExpression is a copyable value type — it lives inside QList<Rule>. The compiled regex for a Regex leaf is built eagerly at construction time (in makeLeaf / fromJson) and stored in a shared_ptr so value-copies share the same compiled program rather than recompiling.

Thread-safety. evaluate() performs no lazy mutation of the MatchExpression itself — it only reads the already-compiled program. It is therefore reentrant. It is NOT, however, safe to call concurrently on two MatchExpression copies that share a Regex leaf: the shared shared_ptr<QRegularExpression> means both copies dispatch through one QRegularExpression instance, and QRegularExpression::match() mutates that instance's internal state (it is not thread-safe for concurrent match() calls on the same object). Callers that evaluate copies of a regex-bearing expression from multiple threads must serialize those calls themselves.

An empty All{} is the always-true catch-all — the migrated provider default. An empty Any{} / None{} are always-false / always-true respectively, following the standard fold identities.

Member Enumeration Documentation

◆ Kind

Tree node kind.

Enumerator
Leaf 

a single field/op/value predicate

All 

AND — every child must match.

Any 

OR — at least one child must match.

None 

NOT-any — no child may match.

Constructor & Destructor Documentation

◆ MatchExpression()

PhosphorRules::MatchExpression::MatchExpression ( )
inline

Default-constructs an empty All{} — the always-true catch-all.

Member Function Documentation

◆ children()

const QList< MatchExpression > & PhosphorRules::MatchExpression::children ( ) const
inline

Composite accessor — empty for a leaf.

◆ evaluate()

bool PhosphorRules::MatchExpression::evaluate ( const WindowQuery & query) const

Evaluate this expression against query.

A leaf predicate over an absent window field evaluates false. Composites fold per their kind. The empty All{} returns true.

Reentrant, but not safe to call concurrently on copies that share a Regex leaf — see the class-level thread-safety note. Callers must serialize concurrent evaluation of regex-bearing expressions.

◆ fromJson()

std::optional< MatchExpression > PhosphorRules::MatchExpression::fromJson ( const QJsonObject & obj)
static

Strict loader — returns nullopt on a malformed / invalid expression.

A pathologically deep composite tree (All{All{All{…}}}) is rejected: nesting deeper than kMaxParseDepth levels short-circuits to nullopt with a logged diagnostic, before the recursion would blow the stack. The cap is generous — a hand-authored rule never approaches it; only a malicious or corrupt store can.

◆ isCatchAll()

bool PhosphorRules::MatchExpression::isCatchAll ( ) const
inline

True if this is the empty catch-all All{} — matches every query.

◆ isContextOnly()

bool PhosphorRules::MatchExpression::isContextOnly ( ) const

True if this expression references only context fields (ScreenId / VirtualDesktop / Activity / Mode / TiledWindowCount) — i.e.

a windowless context rule. An empty catch-all is context-only by this definition.

◆ isLeaf()

bool PhosphorRules::MatchExpression::isLeaf ( ) const
inline

◆ isValid()

bool PhosphorRules::MatchExpression::isValid ( ) const

True if this expression is structurally well-formed: every leaf has a field/operator combination that can actually match (a string operator on a numeric field is rejected), and Regex patterns compile.

◆ kind()

Kind PhosphorRules::MatchExpression::kind ( ) const
inline

◆ makeAll()

MatchExpression PhosphorRules::MatchExpression::makeAll ( const QList< MatchExpression > & children)
static

Constructs a composite expression.

◆ makeAny()

MatchExpression PhosphorRules::MatchExpression::makeAny ( const QList< MatchExpression > & children)
static

◆ makeLeaf() [1/2]

MatchExpression PhosphorRules::MatchExpression::makeLeaf ( const Predicate & predicate)
static

Constructs a leaf predicate expression.

◆ makeLeaf() [2/2]

MatchExpression PhosphorRules::MatchExpression::makeLeaf ( Field field,
Operator op,
const QVariant & value )
static

◆ makeNone()

MatchExpression PhosphorRules::MatchExpression::makeNone ( const QList< MatchExpression > & children)
static

◆ negatesAnyField()

bool PhosphorRules::MatchExpression::negatesAnyField ( const QSet< Field > & fields) const

True if a leaf predicate on one of fields appears anywhere INSIDE a none{} negation (at any nesting depth).

This is the negation-polarity guard for resolvers whose query cannot answer a field. An absent field makes its leaf evaluate FALSE, which is the safe, inert outcome for a positive leaf — but none{} matches when no child matched, so the same absence makes a NEGATED leaf match unconditionally: none{AppId == firefox} on a windowless context query matches every context. A resolver that does not stamp a field must therefore exclude rules that NEGATE it; positive references stay admitted, because inert-false is exactly the documented behaviour for them and an any{} rule's other branches may legitimately fire.

◆ operator!=()

bool PhosphorRules::MatchExpression::operator!= ( const MatchExpression & other) const
inline

◆ operator==()

bool PhosphorRules::MatchExpression::operator== ( const MatchExpression & other) const

◆ predicate()

const Predicate & PhosphorRules::MatchExpression::predicate ( ) const
inline

Leaf accessor — only meaningful when isLeaf().

◆ referencesAnyField()

bool PhosphorRules::MatchExpression::referencesAnyField ( const QSet< Field > & fields) const

True if any leaf predicate anywhere in the tree (including inside none{} negations) tests one of fields.

This is a purely structural query about what the expression mentions, independent of whether it matches any particular window — callers use it to ask "does this rule deliberately target a window type?" (e.g. a rule that references IsTransient / WindowType is opting into transient windows, whereas a class-only rule that merely happens to match a tooltip is not). An empty composite references nothing and returns false.

◆ toJson()

QJsonObject PhosphorRules::MatchExpression::toJson ( ) const

Member Data Documentation

◆ kMaxParseDepth

int PhosphorRules::MatchExpression::kMaxParseDepth = 32
staticconstexpr

Hard cap on the JSON parser's recursion depth.

A composite at depth N may contain children at depth N + 1 — the cap rejects any tree whose composite nesting would exceed this limit.


The documentation for this class was generated from the following file: