OLD | NEW |
(Empty) | |
| 1 # Providing Kythe Data |
| 2 |
| 3 **Note:** Kythe support is experimental and might be removed or changed without |
| 4 notice. |
| 5 |
| 6 [Kythe][kythe] is, in their own words, "A pluggable, (mostly) language-agnostic |
| 7 ecosystem for building tools that work with code." The analysis server can be |
| 8 used to produce the data that should be sent to Kythe. In other words, the |
| 9 analysis server is (almost) a Kythe indexer. (The data needs to be converted |
| 10 from a Json representation to a protobuf format before being sent to Kythe.) |
| 11 |
| 12 ## Implementation details |
| 13 |
| 14 When appropriate, the analysis server will send your plugin a |
| 15 `kythe.getKytheEntries` request. The request includes the `file` for which data |
| 16 should be generated. The data consists of a list of `KytheEntry`s. |
| 17 |
| 18 When a `kythe.getKytheEntries` request is received, the method |
| 19 `handleKytheGetKytheEntries` will be invoked. This method is responsible for |
| 20 returning a response that contains the entries to be sent to Kythe. |
| 21 |
| 22 The easiest way to implement this method is by adding the classes `EntryMixin` |
| 23 and `DartEntryMixin` (from `package:analyzer_plugin/plugin/kythe_mixin.dart`) to |
| 24 the list of mixins for your subclass of `ServerPlugin`. This will leave you with |
| 25 one abstract method that you need to implement: `getEntryContributors`. That |
| 26 method is responsible for returning a list of `EntryContributor`s. It is the |
| 27 entry contributors that produce the actual entries. (Most plugins will only need |
| 28 a single entry contributor.) |
| 29 |
| 30 To write an entry contributor, create a class that implements |
| 31 `EntryContributor`. The interface defines a single method named |
| 32 `computeEntries`. The method has two arguments: an `EntryRequest` that describes |
| 33 the file to be indexed and an `EntryCollector` through which entries are to be |
| 34 added. |
| 35 |
| 36 If you mix in the class `DartEntryMixin`, then the request will be an instance |
| 37 of `DartEntryRequest`, which also has analysis results. |
| 38 |
| 39 ## Example |
| 40 |
| 41 Start by creating a class that implements `EntryContributor`, then implement the |
| 42 method `computeEntries`. This method is typically implemented by creating a |
| 43 visitor (such as an AstVisitor) that can visit the results of the analysis (such |
| 44 as a CompilationUnit) and extract the navigation information from the analysis |
| 45 result. |
| 46 |
| 47 For example, your contributor might look something like the following: |
| 48 |
| 49 ```dart |
| 50 class MyEntryContributor implements EntryContributor { |
| 51 @override |
| 52 void computeEntries(EntryRequest request, EntryCollector collector) { |
| 53 if (request is DartEntryRequest) { |
| 54 EntryVisitor visitor = new EntryVisitor(collector); |
| 55 request.result.unit.accept(visitor); |
| 56 } |
| 57 } |
| 58 } |
| 59 |
| 60 class EntryVisitor extends RecursiveAstVisitor { |
| 61 final EntryCollector collector; |
| 62 |
| 63 EntryVisitor(this.collector); |
| 64 |
| 65 @override |
| 66 void visitSimpleIdentifier(SimpleIdentifier node) { |
| 67 // ... |
| 68 } |
| 69 } |
| 70 ``` |
| 71 |
| 72 Given a contributor like the one above, you can implement your plugin similar to |
| 73 the following: |
| 74 |
| 75 ```dart |
| 76 class MyPlugin extends ServerPlugin with EntryMixin, DartEntryMixin { |
| 77 // ... |
| 78 |
| 79 @override |
| 80 List<EntryContributor> getEntryContributors(String path) { |
| 81 return <EntryContributor>[new MyEntryContributor()]; |
| 82 } |
| 83 } |
| 84 ``` |
| 85 |
| 86 [kythe]: http://kythe.io/ |
OLD | NEW |