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, SourceSpan
. It
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 SourceSpan.message()
.
When parsing code from a file, SourceFile
is useful. Not only does it provide
an efficient means of computing line and column numbers, SourceFile.span()
returns special FileSpan
s that are able to provide more context for their
error messages.
The 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.
The 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 0xFFFF
are passed to new
SourceFile.decoded()
is now considered deprecated.
SourceSpan.highlight()
and SourceSpan.message()
.SourceSpan.highlight()
, which returns just the highlighted text that
would be included in SourceSpan.message()
.SourceSpanException.message
, SourceSpanFormatException.source
, and
SourceSpanWithContext.context
to be overridden in strong mode.FileSpan.start
and FileSpan.end
. In 1.2.0 these
were mistakenly changed from FileLocation
to SourceLocation
.Deprecated: Extending SourceLocation
directly is deprecated. Instead,
extend the new SourceLocationBase
class or mix in the new
SourceLocationMixin
mixin.
Dramatically improve the performance of FileLocation
.
getLine()
in SourceFile
when repeatedly called.FileSpan.union
could throw an exception for
external implementations of FileSpan
.==
, but not hashCode
.FileSpan.compareTo
, FileSpan.==
, FileSpan.union
, and FileSpan.expand
no longer throw exceptions for external implementations of FileSpan
.
FileSpan.hashCode
now fully agrees with FileSpan.==
.
SourceSpanWithContext
to allow multiple occurrences of
text
within context
.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.SourceLocation
.Avoid unintentionally allocating extra objects for internal FileSpan
operations.
Ensure that SourceSpan.operator==
works on arbitrary Object
s.
FileSpan
.This package was extracted from the
source_maps
package, but the
API has many differences. Among them:
Span
has been renamed to SourceSpan
and Location
has been renamed to
SourceLocation
to clarify their purpose and maintain consistency with the
package name. Likewise, SpanException
is now SourceSpanException
and
SpanFormatException
is not SourceSpanFormatException
.
FixedSpan
and FixedLocation
have been rolled into the Span
and
Location
classes, respectively.
SourceFile
is more aggressive about validating its arguments. Out-of-bounds
lines, columns, and offsets will now throw errors rather than be silently
clamped.
SourceSpan.sourceUrl
, SourceLocation.sourceUrl
, and SourceFile.url
now
return Uri
objects rather than String
s. The constructors allow either
String
s or Uri
s.
Span.getLocationMessage
and SourceFile.getLocationMessage
are now
SourceSpan.message
and SourceFile.message
, respectively. Rather than
taking both a useColor
and a color
parameter, they now take a single
color
parameter that controls both whether and which color is used.
Span.isIdentifier
has been removed. This property doesn't make sense outside
of a source map context.
SourceFileSegment
has been removed. This class wasn't widely used and was
inconsistent in its choice of which parameters were considered relative and
which absolute.
Add this to your package's pubspec.yaml file:
dependencies:
source_span: "^1.4.0"
You can install packages from the command line:
with pub:
$ pub get
with Flutter:
$ flutter packages get
Alternatively, your editor might support pub get
or packages get
.
Check the docs for your editor to learn more.
Now in your Dart code, you can use:
import 'package:source_span/source_span.dart';
Version | Uploaded | Documentation | Archive |
---|---|---|---|
1.4.0 | May 17, 2017 |
|
|
1.3.1 | Jan 7, 2017 |
|
|
1.3.0 | Nov 8, 2016 |
|
|
1.2.4 | Oct 21, 2016 |
|
|
1.2.3 | Jun 9, 2016 |
|
|
1.2.2 | Mar 2, 2016 |
|
|
1.2.1 | Sep 30, 2015 |
|
|
1.2.0 | Sep 2, 2015 |
|
|
1.1.6 | Sep 2, 2015 |
|
|
1.1.5 | Sep 1, 2015 |
|
|
We analyzed this package on Apr 23, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:
Popularity:
Describes how popular the package is relative to other packages.
[more]
|
95 | / 100 |
Health:
Code health derived from static analysis.
[more]
|
99 | / 100 |
Maintenance:
Reflects how tidy and up-to-date the package is.
[more]
|
100 | / 100 |
Overall score:
Weighted score of the above.
[more]
|
97 |
Detected platforms: Flutter, web, other
No platform restriction found in primary library
package:source_span/source_span.dart
.
The description is too short.
Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.
Fix analysis and formatting issues.
Analysis or formatting checks reported 6 hints.
Run
dartfmt
to formatlib/src/colors.dart
.Run
dartfmt
to formatlib/src/file.dart
.Similar analysis of the following files failed:
lib/src/location.dart
(hint)lib/src/location_mixin.dart
(hint)lib/src/span_mixin.dart
(hint)lib/src/span_with_context.dart
(hint)
Maintain an example.
Create a short demo in the
example/
directory to show how to use this package. Common file name patterns include:main.dart
,example.dart
or you could also usesource_span.dart
.
Use analysis_options.yaml
.
Rename old
.analysis_options
file toanalysis_options.yaml
.