Brian Wilkerson
d1a2a43d54
R=scheglov@google.com Review-Url: https://codereview.chromium.org/3006703002 .
90 lines
3.4 KiB
Markdown
90 lines
3.4 KiB
Markdown
# Providing Highlighting Information
|
|
|
|
Highlighting information is used by clients to help users identify different
|
|
syntactic and semantic regions of their code.
|
|
|
|
Syntactic highlighting is highlighting that is based completely on the syntax of
|
|
the code. For example, editors will often provide unique colors for comments,
|
|
string literals, and numeric literals.
|
|
|
|
Semantic highlighting is highlighting that is based on semantic information. For
|
|
example, an editor could highlight references to fields differently than
|
|
references to local variables. Editors could also highlight references to
|
|
deprecated elements differently.
|
|
|
|
## Implementation details
|
|
|
|
Highlighting information is available through a subscription. If the server has
|
|
subscribed for highlighting information in some set of files, then the plugin
|
|
should send the information in an `analysis.highlights` notification whenever
|
|
the information needs to be updated.
|
|
|
|
When a notification needs to be sent, the method `sendHighlightsNotification`
|
|
will be invoked. This method is responsible for sending the notification.
|
|
|
|
The easiest way to add support for this notification is by adding the classes
|
|
`HighlightsMixin` and `DartHighlightsMixin` (from
|
|
`package:analyzer_plugin/plugin/highlights_mixin.dart`) to the list of mixins
|
|
for your subclass of `ServerPlugin`. This will leave you with one abstract
|
|
method that you need to implement: `getHighlightsContributors`. That method is
|
|
responsible for returning a list of `HighlightsContributor`s. It is the
|
|
highlights contributors that produce the actual highlighting information. (Most
|
|
plugins will only need a single highlights contributor.)
|
|
|
|
To write a highlights contributor, create a class that implements
|
|
`HighlightsContributor`. The interface defines a single method named
|
|
`computeHighlights`. The method has two arguments: an `HighlightsRequest` that
|
|
describes the file for which highlighting information is being requested and an
|
|
`HighlightsCollector` through which highlighting information is to be added.
|
|
|
|
If you mix in the class `DartHighlightsMixin`, then the request will be an
|
|
instance of `DartHighlightsRequest`, which also has analysis results.
|
|
|
|
## Example
|
|
|
|
Start by creating a class that implements `HighlightsContributor`, then
|
|
implement the method `computeHighlights`. This method is typically implemented
|
|
by creating a visitor (such as an AstVisitor) that can visit the results of the
|
|
analysis (such as a CompilationUnit) and extract the highlighting information
|
|
from the analysis result.
|
|
|
|
For example, your contributor might look something like the following:
|
|
|
|
```dart
|
|
class MyHighlightsContributor implements HighlightsContributor {
|
|
@override
|
|
void computeHighlights(
|
|
HighlightsRequest request, HighlightsCollector collector) {
|
|
if (request is DartHighlightsRequest) {
|
|
HighlightsVisitor visitor = new HighlightsVisitor(collector);
|
|
request.result.unit.accept(visitor);
|
|
}
|
|
}
|
|
}
|
|
|
|
class HighlightsVisitor extends RecursiveAstVisitor {
|
|
final HighlightsCollector collector;
|
|
|
|
HighlightsVisitor(this.collector);
|
|
|
|
@override
|
|
void visitSimpleIdentifier(SimpleIdentifier node) {
|
|
// ...
|
|
}
|
|
}
|
|
```
|
|
|
|
Given a contributor like the one above, you can implement your plugin similar to
|
|
the following:
|
|
|
|
```dart
|
|
class MyPlugin extends ServerPlugin with HighlightsMixin, DartHighlightsMixin {
|
|
// ...
|
|
|
|
@override
|
|
List<HighlightsContributor> getHighlightsContributors(String path) {
|
|
return <HighlightsContributor>[new MyHighlightsContributor()];
|
|
}
|
|
}
|
|
```
|