Brian Wilkerson
2d204c548b
R=jwren@google.com Review-Url: https://codereview.chromium.org/3004743002 .
87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
# Providing Kythe Data
|
|
|
|
**Note:** Kythe support is experimental and might be removed or changed without
|
|
notice.
|
|
|
|
[Kythe][kythe] is, in their own words, "A pluggable, (mostly) language-agnostic
|
|
ecosystem for building tools that work with code." The analysis server can be
|
|
used to produce the data that should be sent to Kythe. In other words, the
|
|
analysis server is (almost) a Kythe indexer. (The data needs to be converted
|
|
from a Json representation to a protobuf format before being sent to Kythe.)
|
|
|
|
## Implementation details
|
|
|
|
When appropriate, the analysis server will send your plugin a
|
|
`kythe.getKytheEntries` request. The request includes the `file` for which data
|
|
should be generated. The data consists of a list of `KytheEntry`s.
|
|
|
|
When a `kythe.getKytheEntries` request is received, the method
|
|
`handleKytheGetKytheEntries` will be invoked. This method is responsible for
|
|
returning a response that contains the entries to be sent to Kythe.
|
|
|
|
The easiest way to implement this method is by adding the classes `EntryMixin`
|
|
and `DartEntryMixin` (from `package:analyzer_plugin/plugin/kythe_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: `getEntryContributors`. That
|
|
method is responsible for returning a list of `EntryContributor`s. It is the
|
|
entry contributors that produce the actual entries. (Most plugins will only need
|
|
a single entry contributor.)
|
|
|
|
To write an entry contributor, create a class that implements
|
|
`EntryContributor`. The interface defines a single method named
|
|
`computeEntries`. The method has two arguments: an `EntryRequest` that describes
|
|
the file to be indexed and an `EntryCollector` through which entries are to be
|
|
added.
|
|
|
|
If you mix in the class `DartEntryMixin`, then the request will be an instance
|
|
of `DartEntryRequest`, which also has analysis results.
|
|
|
|
## Example
|
|
|
|
Start by creating a class that implements `EntryContributor`, then implement the
|
|
method `computeEntries`. 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 navigation information from the analysis
|
|
result.
|
|
|
|
For example, your contributor might look something like the following:
|
|
|
|
```dart
|
|
class MyEntryContributor implements EntryContributor {
|
|
@override
|
|
void computeEntries(EntryRequest request, EntryCollector collector) {
|
|
if (request is DartEntryRequest) {
|
|
EntryVisitor visitor = new EntryVisitor(collector);
|
|
request.result.unit.accept(visitor);
|
|
}
|
|
}
|
|
}
|
|
|
|
class EntryVisitor extends RecursiveAstVisitor {
|
|
final EntryCollector collector;
|
|
|
|
EntryVisitor(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 EntryMixin, DartEntryMixin {
|
|
// ...
|
|
|
|
@override
|
|
List<EntryContributor> getEntryContributors(String path) {
|
|
return <EntryContributor>[new MyEntryContributor()];
|
|
}
|
|
}
|
|
```
|
|
|
|
[kythe]: http://kythe.io/
|