Add a string_scanner package.

pkg/string_scanner/lib/string_scanner.dart

Index: pkg/string_scanner/lib/string_scanner.dart
diff --git a/pkg/shelf/lib/src/string_scanner.dart b/pkg/string_scanner/lib/string_scanner.dart
similarity index 54%
copy from pkg/shelf/lib/src/string_scanner.dart
copy to pkg/string_scanner/lib/string_scanner.dart
index 834c2d433c53a7289510caa9647b5f068e2827c6..624c090e81f44303744392367c5de8f5c9db6a8c 100644
--- a/pkg/shelf/lib/src/string_scanner.dart
+++ b/pkg/string_scanner/lib/string_scanner.dart
@@ -2,8 +2,10 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-library shelf.string_scanner;
+/// A library for parsing strings using a sequence of patterns.
+library string_scanner;
 
+// TODO(nweiz): Add some integration between this and source maps.
 /// A class that scans through a string using [Pattern]s.
 class StringScanner {
   /// The string being scanned through.
@@ -52,10 +54,30 @@ class StringScanner {
   /// If [pattern] matches at the current position of the string, scans forward
   /// until the end of the match.
   ///
-  /// If [pattern] did not match, throws a [FormatException] with [message].
-  void expect(Pattern pattern, String message) {
+  /// If [pattern] did not match, throws a [FormatException] describing the
+  /// position of the failure. [name] is used in this error as the expected name
+  /// of the pattern being matched; if it's `null`, the pattern itself is used
+  /// instead.
+  void expect(Pattern pattern, {String name}) {
     if (scan(pattern)) return;
-    throw new FormatException(message);
+
+    if (name == null) {
+      if (pattern is RegExp) {
+        name = "/${pattern.pattern.replaceAll("/", "\\/")}/";
+      } else {
+        name = pattern.toString()
+            .replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+        name = '"$name"';
+      }
+    }
+    _fail(name);
+  }
+
+  /// If the string has not been fully consumed, this throws a
+  /// [FormatException].
+  void expectDone() {
+    if (isDone) return;
+    _fail("no more input");
   }
 
   /// Returns whether or not [pattern] matches at the current position of the
@@ -66,4 +88,26 @@ class StringScanner {
     _lastMatch = pattern.matchAsPrefix(string, position);
     return _lastMatch != null;
   }
+
+  // TODO(nweiz): Make this handle long lines more gracefully.
+  /// Throws a [FormatException] describing that [name] is expected at the
+  /// current position in the string.
+  void _fail(String name) {
+    var newlines = "\n".allMatches(string.substring(0, position)).toList();
+    var line = newlines.length + 1;
+    var column;
+    var lastLine;
+    if (newlines.isEmpty) {
+      column = position + 1;
+      lastLine = string.substring(0, position);
+    } else {
+      column = position - newlines.last.end + 1;
+      lastLine = string.substring(newlines.last.end, position);
+    }
+    lastLine += rest.replaceFirst(new RegExp(r"\n.*"), '');
+    throw new FormatException(
+        "Expected $name on line $line, column $column.\n"
+        "$lastLine\n"
+        "${new List.filled(column - 1, ' ').join()}^");
+  }
 }