source_span is a library for tracking locations in source code. It's designed
to provide a standard representation for source code locations and spans so that
disparate packages can easily pass them among one another, and to make it easy
to generate human-friendly messages associated with a given piece of code.
The most commonly-used class is the package's namesake,
represents a span of characters in some source file, and is often attached to an
object that has been parsed to indicate where it was parsed from. It provides
access to the text of the span via
SourceSpan.text and can be used to produce
human-friendly messages using
When parsing code from a file,
SourceFile is useful. Not only does it provide
an efficient means of computing line and column numbers,
FileSpans that are able to provide more context for their
- Add support for highlighting multiple source spans at once, providing more
context for span-based messages. This is exposed through the new APIs
SourceSpan.messageMultiple()(both extension methods),
- Fix padding around line numbers that are powers of 10 in
- Fix a bug where
FileSpan.highlight()would crash for spans that covered a trailing newline and a single additional empty line.
FileSpan.highlight()now properly highlights point spans at the beginning of lines.
- Fix an edge case where
FileSpan.highlight()would put the highlight indicator in the wrong position when highlighting a point span after the end of a file.
SourceFile.span()now goes to the end of the file by default, rather than ending one character before the end of the file. This matches the documented behavior.
FileSpan.contextnow includes the full line on which the span appears for empty spans at the beginning and end of lines.
Fix an edge case where
FileSpan.highlight()could crash when highlighting a span that ended with an empty line.
Produce better source span highlights for multi-line spans that cover the entire last line of the span, including the newline.
Produce better source span highlights for spans that contain Windows-style newlines.
Improve the output of
- They now include line numbers.
- They will now print every line of a multiline span.
- They will now use Unicode box-drawing characters by default (this can be
- Set max SDK version to
<3.0.0, and adjust other dependencies.
new SourceFile()constructor is deprecated. This constructed a source file from a string's runes, rather than its code units, which runs counter to the way Dart handles strings otherwise. The
new StringFile.fromString()constructor (see below) should be used instead.
new SourceFile.fromString()constructor was added. This works like
new SourceFile(), except it uses code units rather than runes.
The current behavior when characters larger than
0xFFFFare passed to
new SourceFile.decoded()is now considered deprecated.
- Properly highlight spans for lines that include tabs with
SourceSpan.highlight(), which returns just the highlighted text that would be included in
- Fix a new strong mode error.
- Fix a bug where a point span at the end of a file without a trailing newline would be printed incorrectly.
SourceSpanWithContext.contextto be overridden in strong mode.
- Fix the declared type of
FileSpan.end. In 1.2.0 these were mistakenly changed from
SourceLocationdirectly is deprecated. Instead, extend the new
SourceLocationBaseclass or mix in the new
Dramatically improve the performance of
SourceFilewhen repeatedly called.
- Fixed another case in which
FileSpan.unioncould throw an exception for external implementations of
- Eliminated dart2js warning about overriding
==, but not
FileSpan.expandno longer throw exceptions for external implementations of
FileSpan.hashCodenow fully agrees with
- Fixed validation in
SourceSpanWithContextto allow multiple occurrences of
FileSpan's context to include the full span text, not just the first line of it.
SourceSpanWithContext: a span that also includes the full line of text that contains the span.
- Cleanup equality operator to accept any Object rather than just a
Avoid unintentionally allocating extra objects for internal
SourceSpan.operator==works on arbitrary
- Use a more compact internal representation for
This package was extracted from the
source_maps package, but the
API has many differences. Among them:
Spanhas been renamed to
Locationhas been renamed to
SourceLocationto clarify their purpose and maintain consistency with the package name. Likewise,
FixedLocationhave been rolled into the
SourceFileis more aggressive about validating its arguments. Out-of-bounds lines, columns, and offsets will now throw errors rather than be silently clamped.
Uriobjects rather than
Strings. The constructors allow either
SourceFile.message, respectively. Rather than taking both a
colorparameter, they now take a single
colorparameter that controls both whether and which color is used.
Span.isIdentifierhas been removed. This property doesn't make sense outside of a source map context.
SourceFileSegmenthas been removed. This class wasn't widely used and was inconsistent in its choice of which parameters were considered relative and which absolute.
Use this package as a library
1. Depend on it
Add this to your package's pubspec.yaml file:
dependencies: source_span: ^1.6.0
2. Install it
You can install packages from the command line:
$ pub get
$ flutter pub get
Alternatively, your editor might support
pub get or
flutter pub get.
Check the docs for your editor to learn more.
3. Import it
Now in your Dart code, you can use:
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
We analyzed this package on Feb 29, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:
- Dart: 2.7.1
- pana: 0.13.5
Maintain an example. (-10 points)
Create a short demo in the
example/ directory to show how to use this package.
Common filename patterns include
source_span.dart. Packages with multiple examples should provide
For more information see the pub package layout conventions.
The package description is too short. (-7 points)
Add more detail to the
description field of
pubspec.yaml. Use 60 to 180 characters to describe the package, what it does, and its target use case.