HierarchyQuery class abstract

Abstract base class for hierarchy search queries.

A HierarchyQuery encapsulates the matching strategy (how names are compared) independently of the tree traversal (which is always performed by HierarchyService).

Contract with HierarchyService

The service walks the HierarchyOccurrence tree depth-first. At each node it calls:

1. matchOccurrence — does this occurrence name satisfy the query at the current match state? Returns a set of successor states (empty = prune this branch).
2. matchSignal — does this signal name satisfy the query at the current match state?
3. isComplete — have all parts of the query been consumed at the given state?

"Match state" is an opaque integer that the query owns. It typically tracks how many segments/tokens of the query have been consumed so far. The initial state is always 0.

Crossing hierarchy boundaries

If crossesBoundaries is true the service will, at each depth, additionally try advancing with the current state even when the occurrence doesn't match — allowing matches to span across intermediate hierarchy levels (like ** in glob patterns).

Subclassing

Implement a concrete query by overriding at least matchOccurrence, matchSignal, isComplete, and segmentCount.

The factory HierarchyQuery.prefix creates the default prefix-substring query. HierarchyQuery.regex creates a regex/glob query.

// Custom fuzzy query
class FuzzyQuery extends HierarchyQuery {
  FuzzyQuery(String rawQuery)
      : super(rawQuery, target: SearchTarget.signals);
  ...
}