Add LineScanner and SpanScanner classes to string_scanner.

pkg/string_scanner/lib/src/exception.dart

Index: pkg/string_scanner/lib/src/exception.dart
diff --git a/pkg/string_scanner/lib/src/exception.dart b/pkg/string_scanner/lib/src/exception.dart
new file mode 100644
index 0000000000000000000000000000000000000000..c3986871a8cff41e0f5219616c6700faa7ac8964
--- /dev/null
+++ b/pkg/string_scanner/lib/src/exception.dart
@@ -0,0 +1,37 @@
+// Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
+// 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 string_scanner.exception;
+
+import 'package:source_maps/source_maps.dart';
+
+/// An exception thrown by a [StringScanner] that failed to parse a string.
+class StringScannerException implements FormatException {
+  /// The error message.
+  final String message;
+
+  /// The source string being parsed.
+  final String string;

[Bob Nystrom, 2014/05/28 21:28:57]

Given that you use "sourceUrl" below, how about "source" for this?

[nweiz, 2014/05/28 23:56:34]

I think it's better that it match [StringScanner.string].

+
+  /// The URL of the source file being parsed.
+  ///
+  /// This may be `null`, indicating that the source URL is unknown.
+  final Uri sourceUrl;
+
+  /// The span within [string] that caused the exception.
+  final Span span;
+
+  StringScannerException(this.message, this.string, this.sourceUrl, this.span);
+
+  /// Returns a detailed description of this exception.
+  ///
+  /// If [useColors] is true, the section of the source that caused the
+  /// exception will be colored using ANSI color codes. By default, it's colored
+  /// red, but a different ANSI code may passed via [color].
+  String toString({bool useColors: false, String color}) {

[Bob Nystrom, 2014/05/28 21:28:57]

I'd personally prefer not using a default value here. It likely won't do what
the user expects if they pass in null for useColors. (That may happen if they
are forwarding a default value from their method. For example, if you didn't
want to provide a default value here and instead just forward to
.getLocationMessage() to "inherit" its default value, it won't actually do the
right thing. The null will override the default value.)

[nweiz, 2014/05/28 23:56:34]

I generally agree for non-boolean values, but for booleans I think there are
good reasons to include the default. The user needs to understand what the
default value is regardless of whether it's declared explicitly, much more than
for non-boolean values, since they're directly deciding its value whether or not
they pass in a value. Calls to methods with boolean parameters are never
resilient to changes in the default value.

[Bob Nystrom, 2014/05/29 15:51:00]

I definitely agree that users need to understand what the default value is. This
is true for other primitive types too where the user doesn't expect them to be
nullable. But they could get that understanding through documentation.

I don't understand what "since they're directly deciding its value whether or
not they pass in a value." means. My concern is that I think:

someMethod();
someMethod(anArg: null);

should do the same thing. With default values, they don't.
I'm less concerned about the default changing (which is definitely a breaking
change in a public API) as I am about having a single point of truth and making
forwarding work transparently.

[nweiz, 2014/05/29 20:06:26]

I don't think allowing users to pass null to any optional argument is an
important invariant. The invariant I'm concerned about is that the function's
internal logic doesn't need to be duplicated by the caller.

I think of functions with optional (or named) arguments as analogous to
overloads in other languages: foo(mandatoryArg) has one API, and
foo(manadatoryArg, optionalArg) has a similar but distinct API. From the
perspective of the caller, the default value of optionalArg is whatever it needs
to be to make the latter API work like the former. The specific value that makes
this true shouldn't be encoded in the caller's code.

Optional booleans don't work exactly the same way, though. They're more
analogous to fooWithTrue(mandatoryArg) and fooWithFalse(mandatoryArg) functions.
When calling a method with an optional boolean, the caller always has to decide
whether they want that boolean to be true or false; they effectively have to
decide whether they're calling fooWithTrue or fooWithFalse.

What I'm trying to say is that the logic of whether the default value is "true"
or "false" isn't internal to the function. It's something the caller has to be
aware of, and as such I think it's fine to duplicate it.

+    return "Error on " + span.getLocationMessage(
+        message, useColors: useColors, color: color);
+  }
+}
+