From fc676d01b1854c32abc928960f09653ca1b0fe0c Mon Sep 17 00:00:00 2001
From: Lukas Renggli <renggli@gmail.com>
Date: Sun, 30 Oct 2022 14:59:49 +0100
Subject: [PATCH] Add some more `@useResult` to parser constructors.

---
 lib/src/debug/profile.dart        |  3 +++
 lib/src/debug/progress.dart       |  3 +++
 lib/src/debug/trace.dart          |  3 +++
 lib/src/definition/grammar.dart   |  1 +
 lib/src/definition/reference.dart | 13 +++++++++++++
 lib/src/expression/builder.dart   |  4 ++++
 lib/src/reflection/optimize.dart  |  4 ++++
 lib/src/reflection/transform.dart |  3 +++
 8 files changed, 34 insertions(+)

diff --git a/lib/src/debug/profile.dart b/lib/src/debug/profile.dart
index 1afcd70f..8fce85b8 100644
--- a/lib/src/debug/profile.dart
+++ b/lib/src/debug/profile.dart
@@ -1,3 +1,5 @@
+import 'package:meta/meta.dart';
+
 import '../core/parser.dart';
 import '../parser/action/continuation.dart';
 import '../reflection/transform.dart';
@@ -24,6 +26,7 @@ import '../shared/types.dart';
 ///
 /// The optional [output] callback can be used to receive [ProfileFrame]
 /// objects with the full profiling information at the end of the parse.
+@useResult
 Parser<T> profile<T>(Parser<T> root,
     {VoidCallback<ProfileFrame> output = print, Predicate<Parser>? predicate}) {
   final frames = <ProfileFrame>[];
diff --git a/lib/src/debug/progress.dart b/lib/src/debug/progress.dart
index 83b93d1e..2189eff8 100644
--- a/lib/src/debug/progress.dart
+++ b/lib/src/debug/progress.dart
@@ -1,3 +1,5 @@
+import 'package:meta/meta.dart';
+
 import '../context/context.dart';
 import '../core/parser.dart';
 import '../parser/action/continuation.dart';
@@ -27,6 +29,7 @@ import '../shared/types.dart';
 ///
 /// The optional [output] callback can be used to continuously receive
 /// [ProgressFrame] updates with the current progress information.
+@useResult
 Parser<T> progress<T>(Parser<T> root,
     {VoidCallback<ProgressFrame> output = print,
     Predicate<Parser>? predicate}) {
diff --git a/lib/src/debug/trace.dart b/lib/src/debug/trace.dart
index 9626c681..acd0dc51 100644
--- a/lib/src/debug/trace.dart
+++ b/lib/src/debug/trace.dart
@@ -1,3 +1,5 @@
+import 'package:meta/meta.dart';
+
 import '../context/context.dart';
 import '../context/result.dart';
 import '../core/parser.dart';
@@ -32,6 +34,7 @@ import '../shared/types.dart';
 ///
 /// The optional [output] callback can be used to continuously receive
 /// [TraceEvent] objects with current enter and exit data.
+@useResult
 Parser<T> trace<T>(Parser<T> root,
     {VoidCallback<TraceEvent> output = print, Predicate<Parser>? predicate}) {
   TraceEvent? parent;
diff --git a/lib/src/definition/grammar.dart b/lib/src/definition/grammar.dart
index 48406fb8..4d000228 100644
--- a/lib/src/definition/grammar.dart
+++ b/lib/src/definition/grammar.dart
@@ -71,6 +71,7 @@ abstract class GrammarDefinition<R> {
   /// The optional [start] reference specifies a different starting production
   /// into the grammar. The optional [arguments] list parametrizes the called
   /// production.
+  @useResult
   Parser<T> build<T>({Function? start, List<Object> arguments = const []}) {
     if (start != null) {
       return resolve(Function.apply(start, arguments));
diff --git a/lib/src/definition/reference.dart b/lib/src/definition/reference.dart
index f357645f..0e20798c 100644
--- a/lib/src/definition/reference.dart
+++ b/lib/src/definition/reference.dart
@@ -1,3 +1,5 @@
+import 'package:meta/meta.dart';
+
 import '../core/parser.dart';
 import 'internal/reference.dart';
 import 'internal/undefined.dart';
@@ -11,6 +13,7 @@ import 'resolve.dart';
 /// using one of the strongly typed alternatives [ref0], [ref1], [ref2], ...
 /// instead.
 @Deprecated('Use [ref0], [ref1], [ref2], ... instead.')
+@useResult
 Parser<T> ref<T>(
   Function function, [
   dynamic arg1 = undefined,
@@ -37,12 +40,14 @@ Parser<T> ref<T>(
 ///
 /// If you function takes arguments, consider one of the typed alternatives
 /// [ref1], [ref2], [ref3], ... instead.
+@useResult
 Parser<T> ref0<T>(Parser<T> Function() function) =>
     ReferenceParser<T>(function, const []);
 
 /// Reference to a production [function] parametrized with 1 argument.
 ///
 /// See [ref0] for a detailed description.
+@useResult
 Parser<T> ref1<T, A1>(
   Parser<T> Function(A1) function,
   A1 arg1,
@@ -52,6 +57,7 @@ Parser<T> ref1<T, A1>(
 /// Reference to a production [function] parametrized with 2 arguments.
 ///
 /// See [ref0] for a detailed description.
+@useResult
 Parser<T> ref2<T, A1, A2>(
   Parser<T> Function(A1, A2) function,
   A1 arg1,
@@ -62,6 +68,7 @@ Parser<T> ref2<T, A1, A2>(
 /// Reference to a production [function] parametrized with 3 arguments.
 ///
 /// See [ref0] for a detailed description.
+@useResult
 Parser<T> ref3<T, A1, A2, A3>(
   Parser<T> Function(A1, A2, A3) function,
   A1 arg1,
@@ -73,6 +80,7 @@ Parser<T> ref3<T, A1, A2, A3>(
 /// Reference to a production [function] parametrized with 4 arguments.
 ///
 /// See [ref0] for a detailed description.
+@useResult
 Parser<T> ref4<T, A1, A2, A3, A4>(
   Parser<T> Function(A1, A2, A3, A4) function,
   A1 arg1,
@@ -85,6 +93,7 @@ Parser<T> ref4<T, A1, A2, A3, A4>(
 /// Reference to a production [function] parametrized with 5 arguments.
 ///
 /// See [ref0] for a detailed description.
+@useResult
 Parser<T> ref5<T, A1, A2, A3, A4, A5>(
   Parser<T> Function(A1, A2, A3, A4, A5) function,
   A1 arg1,
@@ -98,6 +107,7 @@ Parser<T> ref5<T, A1, A2, A3, A4, A5>(
 /// Reference to a production [function] parametrized with 6 arguments.
 ///
 /// See [ref0] for a detailed description.
+@useResult
 Parser<T> ref6<T, A1, A2, A3, A4, A5, A6>(
   Parser<T> Function(A1, A2, A3, A4, A5, A6) function,
   A1 arg1,
@@ -112,6 +122,7 @@ Parser<T> ref6<T, A1, A2, A3, A4, A5, A6>(
 /// Reference to a production [function] parametrized with 7 arguments.
 ///
 /// See [ref0] for a detailed description.
+@useResult
 Parser<T> ref7<T, A1, A2, A3, A4, A5, A6, A7>(
   Parser<T> Function(A1, A2, A3, A4, A5, A6, A7) function,
   A1 arg1,
@@ -127,6 +138,7 @@ Parser<T> ref7<T, A1, A2, A3, A4, A5, A6, A7>(
 /// Reference to a production [function] parametrized with 8 arguments.
 ///
 /// See [ref0] for a detailed description.
+@useResult
 Parser<T> ref8<T, A1, A2, A3, A4, A5, A6, A7, A8>(
   Parser<T> Function(A1, A2, A3, A4, A5, A6, A7, A8) function,
   A1 arg1,
@@ -144,6 +156,7 @@ Parser<T> ref8<T, A1, A2, A3, A4, A5, A6, A7, A8>(
 /// Reference to a production [function] parametrized with 9 arguments.
 ///
 /// See [ref0] for a detailed description.
+@useResult
 Parser<T> ref9<T, A1, A2, A3, A4, A5, A6, A7, A8, A9>(
   Parser<T> Function(A1, A2, A3, A4, A5, A6, A7, A8, A9) function,
   A1 arg1,
diff --git a/lib/src/expression/builder.dart b/lib/src/expression/builder.dart
index 6bbff0e6..ae557ed7 100644
--- a/lib/src/expression/builder.dart
+++ b/lib/src/expression/builder.dart
@@ -1,3 +1,5 @@
+import 'package:meta/meta.dart';
+
 import '../core/parser.dart';
 import '../definition/resolve.dart';
 import '../parser/combinator/settable.dart';
@@ -65,6 +67,7 @@ class ExpressionBuilder<T> {
   final SettableParser<T> _loopback = undefined();
 
   /// Creates a new group of operators that share the same priority.
+  @useResult
   ExpressionGroup<T> group() {
     final group = ExpressionGroup<T>(_loopback);
     _groups.add(group);
@@ -72,6 +75,7 @@ class ExpressionBuilder<T> {
   }
 
   /// Builds the expression parser.
+  @useResult
   Parser<T> build() {
     final parser = _groups.fold<Parser<T>>(
       failure('Highest priority group should define a primitive parser.'),
diff --git a/lib/src/reflection/optimize.dart b/lib/src/reflection/optimize.dart
index 97fb6c6f..0703d760 100644
--- a/lib/src/reflection/optimize.dart
+++ b/lib/src/reflection/optimize.dart
@@ -1,8 +1,11 @@
+import 'package:meta/meta.dart';
+
 import '../core/parser.dart';
 import '../parser/combinator/settable.dart';
 import 'transform.dart';
 
 /// Returns a copy of [parser] with all settable parsers removed.
+@useResult
 @Deprecated('Use `resolve(Parser)` instead.')
 Parser<T> removeSettables<T>(Parser<T> parser) {
   return transformParser(parser, <R>(each) {
@@ -14,6 +17,7 @@ Parser<T> removeSettables<T>(Parser<T> parser) {
 }
 
 /// Returns a copy of [parser] with all duplicates parsers collapsed.
+@useResult
 Parser<T> removeDuplicates<T>(Parser<T> parser) {
   final uniques = <Parser>{};
   return transformParser(parser, <R>(source) {
diff --git a/lib/src/reflection/transform.dart b/lib/src/reflection/transform.dart
index 0ab7b042..0276452c 100644
--- a/lib/src/reflection/transform.dart
+++ b/lib/src/reflection/transform.dart
@@ -1,3 +1,5 @@
+import 'package:meta/meta.dart';
+
 import '../core/parser.dart';
 import 'iterable.dart';
 
@@ -10,6 +12,7 @@ typedef TransformationHandler = Parser<T> Function<T>(Parser<T> parser);
 /// The implementation first creates a copy of each parser reachable in the
 /// input grammar; then the resulting grammar is traversed until all references
 /// to old parsers are replaced with the transformed ones.
+@useResult
 Parser<T> transformParser<T>(Parser<T> parser, TransformationHandler handler) {
   final mapping = Map<Parser, Parser>.identity();
   for (final each in allParser(parser)) {