Add SpanScanner.within().

lib/src/span_scanner.dart

 // 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.
 
 import 'package:source_span/source_span.dart';
 
 import 'eager_span_scanner.dart';
 import 'exception.dart';
 import 'line_scanner.dart';
+import 'relative_span_scanner.dart';
 import 'string_scanner.dart';
 import 'utils.dart';
 
 /// A subclass of [LineScanner] that exposes matched ranges as source map
 /// [Span]s.
 class SpanScanner extends StringScanner implements LineScanner {
   /// The source of the scanner.
   ///
   /// This caches line break information and is used to generate [Span]s.
   final SourceFile _sourceFile;
@@ skipping 42 matching lines @@
   /// situations where the normal course of parsing frequently involves
   /// accessing the current line and column numbers.
   ///
   /// Note that *only* the `line` and `column` fields on the `SpanScanner`
   /// itself and its `LineScannerState` are eagerly computed. To limit their
   /// memory footprint, returned spans and locations will still lazily compute
   /// their line and column numbers.
   factory SpanScanner.eager(String string, {sourceUrl, int position}) =
       EagerSpanScanner;
 
+  /// Creates a new [SpanScanner] that scans within [span].
+  ///
+  /// This scans through [span.text], but emits new spans from [span.file] in
+  /// their appropriate relative positions. The [string] field contains only
+  /// [span.text], and [position], [line], and [column] are all relative to the
+  /// span.
+  factory SpanScanner.within(FileSpan span) = RelativeSpanScanner;
+
   /// Creates a [FileSpan] representing the source range between [startState]
   /// and the current position.
   FileSpan spanFrom(LineScannerState startState, [LineScannerState endState]) {
     var endPosition = endState == null ? position : endState.position;
     return _sourceFile.span(startState.position, endPosition);
   }
 
   bool matches(Pattern pattern) {
     if (!super.matches(pattern)) {
       _lastSpan = null;
@@ skipping 22 matching lines @@
 class _SpanScannerState implements LineScannerState {
   /// The [SpanScanner] that created this.
   final SpanScanner _scanner;
 
   final int position;
   int get line => _scanner._sourceFile.getLine(position);
   int get column => _scanner._sourceFile.getColumn(position);
 
   _SpanScannerState(this._scanner, this.position);
 }