Brian Wilkerson
dd00fc7750
R=scheglov@google.com Review-Url: https://codereview.chromium.org/3004613002 .
81 lines
2.8 KiB
Markdown
81 lines
2.8 KiB
Markdown
# Providing Outlines
|
|
|
|
Outline information is used by clients to allow users to see the structure of
|
|
their code.
|
|
|
|
## Implementation details
|
|
|
|
Outline information is available through a subscription. If the server has
|
|
subscribed for outline information in some set of files, then the plugin should
|
|
send the information in an `analysis.outline` notification whenever the
|
|
information needs to be updated.
|
|
|
|
When a notification needs to be sent, the method `sendOutlineNotification` 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
|
|
`OutlineMixin` and `DartOutlineMixin` (from
|
|
`package:analyzer_plugin/plugin/outline_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: `getOutlineContributors`. That method is
|
|
responsible for returning a list of `OutlineContributor`s. It is the outline
|
|
contributors that produce the actual outline information. (Most plugins will
|
|
only need a single outline contributor.)
|
|
|
|
To write an outline contributor, create a class that implements
|
|
`OutlineContributor`. The interface defines a single method named
|
|
`computeOutline`. The method has two arguments: an `OutlineRequest` that
|
|
describes the file for which outline information is being requested and an
|
|
`OutlineCollector` through which outline information is to be added.
|
|
|
|
If you mix in the class `DartOutlineMixin`, then the request will be an instance
|
|
of `DartOutlineRequest`, which also has analysis results.
|
|
|
|
## Example
|
|
|
|
Start by creating a class that implements `OutlineContributor`, then
|
|
implement the method `computeOutline`. 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 outline information from
|
|
the analysis result.
|
|
|
|
For example, your contributor might look something like the following:
|
|
|
|
```dart
|
|
class MyOutlineContributor implements OutlineContributor {
|
|
@override
|
|
void computeOutline(
|
|
OutlineRequest request, OutlineCollector collector) {
|
|
if (request is DartOutlineRequest) {
|
|
OutlineVisitor visitor = new OutlineVisitor(collector);
|
|
request.result.unit.accept(visitor);
|
|
}
|
|
}
|
|
}
|
|
|
|
class OutlineVisitor extends RecursiveAstVisitor {
|
|
final OutlineCollector collector;
|
|
|
|
OutlineVisitor(this.collector);
|
|
|
|
@override
|
|
void visitClassDeclaration(ClassDeclaration node) {
|
|
// ...
|
|
}
|
|
}
|
|
```
|
|
|
|
Given a contributor like the one above, you can implement your plugin similar to
|
|
the following:
|
|
|
|
```dart
|
|
class MyPlugin extends ServerPlugin with OutlineMixin, DartOutlineMixin {
|
|
// ...
|
|
|
|
@override
|
|
List<OutlineContributor> getOutlineContributors(String path) {
|
|
return <OutlineContributor>[new MyOutlineContributor()];
|
|
}
|
|
}
|
|
```
|