QueryEvaluator

Author: isoos

CHANGELOG.md

@@ -1,6 +1,10 @@
-## 2.0.1
+## 2.1.0
 
-- Naming consistency refactor: `FieldScopeQuery` is returned instead of `FieldScope` (kept and deprecated for compatibility for now).
+- Naming consistency refactor:
+  - `ScopeQuery` is returned instead of `FieldScope`.
+  - `CompareQuery` is returned instead of `FieldCompareQuery`.
+  - Old classes are kept in compatibility mode and are deprecated.
+- Added `QueryEvaluator` to help evaluating queries.
 
 ## 2.0.0
 

lib/src/ast.dart

@@ -12,6 +12,19 @@ class SourcePosition {
   int get length => end - start;
 }
 
+/// Provides an interface for generic query evaluation.
+abstract class QueryEvaluator<R> {
+  R evalText(TextQuery query);
+  R evalPhrase(PhraseQuery query);
+  R evalScope(ScopeQuery query);
+  R evalCompare(CompareQuery query);
+  R evalRange(RangeQuery query);
+  R evalNot(NotQuery query);
+  R evalGroup(GroupQuery query);
+  R evalAnd(AndQuery query);
+  R evalOr(OrQuery query);
+}
+
 /// Base interface for queries.
 abstract class Query {
   const Query({
@@ -35,6 +48,8 @@ abstract class Query {
   ///
   /// If the [Query] cannot be cast to [R] it will throw an exception.
   R cast<R extends Query>() => this as R;
+
+  R eval<R>(QueryEvaluator<R> evaluator);
 }
 
 /// Text query to match [text].
@@ -45,6 +60,9 @@ class TextQuery extends Query {
     required super.position,
   });
 
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalText(this);
+
   @override
   String toString({bool debug = false}) => _debug(debug, text);
 }
@@ -58,13 +76,16 @@ class PhraseQuery extends TextQuery {
     required super.position,
   });
 
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalPhrase(this);
+
   @override
   String toString({bool debug = false}) =>
       '"${children.map((n) => n.toString(debug: debug)).join(' ')}"';
 }
 
 /// Scopes [child] [Query] to be applied only on the [field].
-@Deprecated('Use FieldScopeQuery instead.')
+@Deprecated('Use ScopeQuery instead.')
 class FieldScope extends Query {
   final TextQuery field;
   final Query child;
@@ -75,22 +96,30 @@ class FieldScope extends Query {
     required super.position,
   });
 
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator
+      .evalScope(ScopeQuery(field: field, child: child, position: position));
+
   @override
   String toString({bool debug = false}) =>
       '$field:${child.toString(debug: debug)}';
 }
 
 /// Scopes [child] [Query] to be applied only on the [field].
 // ignore: deprecated_member_use_from_same_package
-class FieldScopeQuery extends FieldScope {
-  const FieldScopeQuery({
+class ScopeQuery extends FieldScope {
+  const ScopeQuery({
     required super.field,
     required super.child,
     required super.position,
   });
+
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalScope(this);
 }
 
 /// Describes a [field] [operator] [text] tripled (e.g. year < 2000).
+@Deprecated('Use CompareQuery instead.')
 class FieldCompareQuery extends Query {
   final TextQuery field;
   final TextQuery operator;
@@ -103,11 +132,29 @@ class FieldCompareQuery extends Query {
     required super.position,
   });
 
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalCompare(CompareQuery(
+      field: field, operator: operator, text: text, position: position));
+
   @override
   String toString({bool debug = false}) =>
       _debug(debug, '$field$operator$text');
 }
 
+/// Describes a [field] [operator] [text] tripled (e.g. year < 2000).
+// ignore: deprecated_member_use_from_same_package
+class CompareQuery extends FieldCompareQuery {
+  CompareQuery({
+    required super.field,
+    required super.operator,
+    required super.text,
+    required super.position,
+  });
+
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalCompare(this);
+}
+
 /// Describes a range query between [start] and [end].
 class RangeQuery extends Query {
   final TextQuery start;
@@ -123,6 +170,9 @@ class RangeQuery extends Query {
     this.endInclusive = true,
   });
 
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalRange(this);
+
   @override
   String toString({bool debug = false}) => _debug(
       debug,
@@ -142,6 +192,9 @@ class NotQuery extends Query {
     required super.position,
   });
 
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalNot(this);
+
   @override
   String toString({bool debug = false}) => '-${child.toString(debug: debug)}';
 }
@@ -154,6 +207,9 @@ class GroupQuery extends Query {
     required super.position,
   });
 
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalGroup(this);
+
   @override
   String toString({bool debug = false}) => '(${child.toString(debug: debug)})';
 }
@@ -167,6 +223,9 @@ class AndQuery extends Query {
     required super.position,
   });
 
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalAnd(this);
+
   @override
   String toString({bool debug = false}) =>
       '(${children.map((n) => n.toString(debug: debug)).join(' ')})';
@@ -181,6 +240,9 @@ class OrQuery extends Query {
     required super.position,
   });
 
+  @override
+  R eval<R>(QueryEvaluator<R> evaluator) => evaluator.evalOr(this);
+
   @override
   String toString({bool debug = false}) =>
       '(${children.map((n) => n.toString(debug: debug)).join(' OR ')})';

lib/src/grammar.dart

@@ -59,7 +59,7 @@ class QueryGrammarDefinition extends GrammarDefinition {
         ref0(exclusion).orEmptyTextQuery();
     return g.token().map((list) => list.value.first == null
         ? list.value.last as Query
-        : FieldScopeQuery(
+        : ScopeQuery(
             field: list.value.first as TextQuery,
             child: list.value.last as Query,
             position: SourcePosition(list.start, list.stop)));
@@ -99,13 +99,13 @@ class QueryGrammarDefinition extends GrammarDefinition {
         position: SourcePosition(list.start, list.stop)));
   }
 
-  Parser<FieldCompareQuery> comparison() {
+  Parser<CompareQuery> comparison() {
     final g = ref0(IDENTIFIER).textQuery() &
         ref0(EXP_SEP).optional() &
         ref0(COMP_OPERATOR).textQuery() &
         ref0(EXP_SEP).optional() &
         ref0(wordOrExact).orEmptyTextQuery();
-    return g.token().map((list) => FieldCompareQuery(
+    return g.token().map((list) => CompareQuery(
         field: list.value[0] as TextQuery,
         operator: list.value[2] as TextQuery,
         text: list.value[4] as TextQuery,

pubspec.yaml

@@ -2,7 +2,7 @@ name: query
 description: >
   Search query parser to implement customized search.
   Supports boolean groups, field scopes, ranges, comparisons...
-version: 2.0.1
+version: 2.1.0
 homepage: https://github.com/isoos/query
 
 environment:

test/query_test.dart

@@ -69,38 +69,38 @@ void main() {
     });
 
     test('scoped', () {
-      parseQuery('a:abc').expect<FieldScopeQuery>('a:<abc>', 0, 5)
+      parseQuery('a:abc').expect<ScopeQuery>('a:<abc>', 0, 5)
         ..field.expect<TextQuery>('<a>', 0, 1)
         ..child.expect<TextQuery>('<abc>', 2, 5);
-      parseQuery('a:"abc"').expect<FieldScopeQuery>('a:"<abc>"', 0, 7);
-      parseQuery('a:"abc 1"').expect<FieldScopeQuery>('a:"<abc> <1>"', 0, 9);
-      parseQuery('a:-"abc 1"').expect<FieldScopeQuery>('a:-"<abc> <1>"', 0, 10);
+      parseQuery('a:"abc"').expect<ScopeQuery>('a:"<abc>"', 0, 7);
+      parseQuery('a:"abc 1"').expect<ScopeQuery>('a:"<abc> <1>"', 0, 9);
+      parseQuery('a:-"abc 1"').expect<ScopeQuery>('a:-"<abc> <1>"', 0, 10);
       parseQuery('NOT field:abc')
           .expect<NotQuery>('-field:<abc>', 0, 13)
           .child
-          .expect<FieldScopeQuery>('field:<abc>', 4, 13)
+          .expect<ScopeQuery>('field:<abc>', 4, 13)
         ..field.expect<TextQuery>('<field>', 4, 9)
         ..child.expect<TextQuery>('<abc>', 10, 13);
-      parseQuery('a:').expect<FieldScopeQuery>('a:<>', 0, 2);
+      parseQuery('a:').expect<ScopeQuery>('a:<>', 0, 2);
       parseQuery('a: AND a').expect<AndQuery>('(a:<> <a>)', 0, 8);
     });
 
     test('special scoped', () {
-      parseQuery('a*:abc').expect<FieldScopeQuery>('a*:<abc>', 0, 6);
-      parseQuery('a%:"abc"').expect<FieldScopeQuery>('a%:"<abc>"', 0, 8);
+      parseQuery('a*:abc').expect<ScopeQuery>('a*:<abc>', 0, 6);
+      parseQuery('a%:"abc"').expect<ScopeQuery>('a%:"<abc>"', 0, 8);
     });
 
     test('compare', () {
-      parseQuery('year < 2000').expect<FieldCompareQuery>('<year<2000>', 0, 11)
+      parseQuery('year < 2000').expect<CompareQuery>('<year<2000>', 0, 11)
         ..field.expect<TextQuery>('<year>', 0, 4)
         ..operator.expect<TextQuery>('<<>', 5, 6)
         ..text.expect<TextQuery>('<2000>', 7, 11);
       parseQuery('field >= "test case"')
-          .expect<FieldCompareQuery>('<field>="test case">', 0, 20)
+          .expect<CompareQuery>('<field>="test case">', 0, 20)
         ..field.expect<TextQuery>('<field>', 0, 5)
         ..operator.expect<TextQuery>('<>=>', 6, 8)
         ..text.expect<PhraseQuery>('"<test> <case>"', 9, 20);
-      parseQuery('year = ').expect<FieldCompareQuery>('<year=>', 0, 7);
+      parseQuery('year = ').expect<CompareQuery>('<year=>', 0, 7);
     });
 
     test('range', () {