Add breaking changes and release 1.0.0.

This makes `.error()` default to empty spans rather than
single-character ones. This better represents the semantics of failing
at a particular position in the text.

It also makes `lastMatch` reset whenever the scanner's position changes.
This makes `.error()` behave more consistently when primarily doing
character-based scanning, since it won't unexpectedly emit an error for
stale match data.

[email protected]

Review URL: https://codereview.chromium.org//2056933002 .

Author: nex3

CHANGELOG.md

@@ -1,3 +1,16 @@
+## 1.0.0
+
+* **Breaking change**: `StringScanner.error()`'s `length` argument now defaults
+  to `0` rather than `1` when no match data is available.
+
+* **Breaking change**: `StringScanner.lastMatch` and related methods are now
+  reset when the scanner's position changes without producing a new match.
+
+**Note**: While the changes in `1.0.0` are user-visible, they're unlikely to
+actually break any code in practice. Unless you know that your package is
+incompatible with 0.1.x, consider using 0.1.5 as your lower bound rather
+than 1.0.0. For example, `string_scanner: ">=0.1.5 <2.0.0"`.
+
 ## 0.1.5
 
 * Add `new SpanScanner.within()`, which scans within a existing `FileSpan`.

lib/src/line_scanner.dart

@@ -26,6 +26,8 @@ class LineScanner extends StringScanner {
   /// This can be used to efficiently save and restore the state of the scanner
   /// when backtracking. A given [LineScannerState] is only valid for the
   /// [LineScanner] that created it.
+  ///
+  /// This does not include the scanner's match information.
   LineScannerState get state =>
       new LineScannerState._(this, position, line, column);
 

lib/src/span_scanner.dart

@@ -38,7 +38,10 @@ class SpanScanner extends StringScanner implements LineScanner {
   ///
   /// This is the span for the entire match. There's no way to get spans for
   /// subgroups since [Match] exposes no information about their positions.
-  FileSpan get lastSpan => _lastSpan;
+  FileSpan get lastSpan {
+    if (lastMatch == null) _lastSpan = null;
+    return _lastSpan;
+  }
   FileSpan _lastSpan;
 
   /// The current location of the scanner.
@@ -102,7 +105,7 @@ class SpanScanner extends StringScanner implements LineScanner {
     if (position == null) {
       position = match == null ? this.position : match.start;
     }
-    if (length == null) length = match == null ? 1 : match.end - match.start;
+    if (length == null) length = match == null ? 0 : match.end - match.start;
 
     var span = _sourceFile.span(position, position + length);
     throw new StringScannerException(message, span, string);

lib/src/string_scanner.dart

@@ -32,14 +32,21 @@ class StringScanner {
     }
 
     _position = position;
+    _lastMatch = null;
   }
   int _position = 0;
 
   /// The data about the previous match made by the scanner.
   ///
   /// If the last match failed, this will be `null`.
-  Match get lastMatch => _lastMatch;
+  Match get lastMatch {
+    // Lazily unset [_lastMatch] so that we avoid extra assignments in
+    // character-by-character methods that are used in core loops.
+    if (_position != _lastMatchPosition) _lastMatch = null;
+    return _lastMatch;
+  }
   Match _lastMatch;
+  int _lastMatchPosition;
 
   /// The portion of the string that hasn't yet been scanned.
   String get rest => string.substring(position);
@@ -118,7 +125,10 @@ class StringScanner {
   /// Returns whether or not [pattern] matched.
   bool scan(Pattern pattern) {
     var success = matches(pattern);
-    if (success) _position = _lastMatch.end;
+    if (success) {
+      _position = _lastMatch.end;
+      _lastMatchPosition = _position;
+    }
     return success;
   }
 
@@ -159,6 +169,7 @@ class StringScanner {
   /// This doesn't move the scan pointer forward.
   bool matches(Pattern pattern) {
     _lastMatch = pattern.matchAsPrefix(string, position);
+    _lastMatchPosition = _position;
     return _lastMatch != null;
   }
 
@@ -181,7 +192,7 @@ class StringScanner {
   ///
   /// If [position] and/or [length] are passed, they are used as the error span
   /// instead. If only [length] is passed, [position] defaults to the current
-  /// position; if only [position] is passed, [length] defaults to 1.
+  /// position; if only [position] is passed, [length] defaults to 0.
   ///
   /// It's an error to pass [match] at the same time as [position] or [length].
   void error(String message, {Match match, int position, int length}) {
@@ -191,7 +202,7 @@ class StringScanner {
     if (position == null) {
       position = match == null ? this.position : match.start;
     }
-    if (length == null) length = match == null ? 1 : match.end - match.start;
+    if (length == null) length = match == null ? 0 : match.end - match.start;
 
     var sourceFile = new SourceFile(string, url: sourceUrl);
     var span = sourceFile.span(position, position + length);

pubspec.yaml

@@ -1,5 +1,5 @@
 name: string_scanner
-version: 0.1.5
+version: 1.0.0
 author: "Dart Team <[email protected]>"
 homepage: https://github.com/dart-lang/string_scanner
 description: >

test/error_test.dart

@@ -59,11 +59,11 @@ void main() {
   });
 
   group("with position and/or length", () {
-    test('defaults to length 1', () {
+    test('defaults to length 0', () {
       var scanner = new StringScanner('foo bar baz');
       scanner.expect('foo ');
       expect(() => scanner.error('oh no!', position: 1),
-          throwsStringScannerException('o'));
+          throwsStringScannerException(''));
     });
 
     test('defaults to the current position', () {

test/string_scanner_test.dart

@@ -261,6 +261,32 @@ void main() {
     });
   });
 
+  group('after a scan', () {
+    var scanner;
+    setUp(() {
+      scanner = new StringScanner('foo bar');
+      expect(scanner.scan('foo'), isTrue);
+    });
+
+    test('readChar returns the first character and unsets the last match', () {
+      expect(scanner.readChar(), equals($space));
+      expect(scanner.lastMatch, isNull);
+      expect(scanner.position, equals(4));
+    });
+
+    test('a matching scanChar returns true and unsets the last match', () {
+      expect(scanner.scanChar($space), isTrue);
+      expect(scanner.lastMatch, isNull);
+      expect(scanner.position, equals(4));
+    });
+
+    test('a matching expectChar returns true and unsets the last match', () {
+      scanner.expectChar($space);
+      expect(scanner.lastMatch, isNull);
+      expect(scanner.position, equals(4));
+    });
+  });
+
   group('at the end of a string', () {
     var scanner;
     setUp(() {
@@ -346,6 +372,13 @@ void main() {
       expect(scanner.rest, equals('bar'));
     });
 
+    test('setting and resetting position clears lastMatch', () {
+      var oldPosition = scanner.position;
+      scanner.position = 1;
+      scanner.position = oldPosition;
+      expect(scanner.lastMatch, isNull);
+    });
+
     test('setting position beyond the string throws an ArgumentError', () {
       expect(() {
         scanner.position = 8;