|
| 1 | +# Writing assists |
| 2 | + |
| 3 | +This package gives analyzer plugin authors the ability to write "quick assists," |
| 4 | +which can make local changes to source code, like small refactorings, from a |
| 5 | +developer's IDE. This document describes briefly how to write such an assist, |
| 6 | +and how to register it in an analyzer plugin. |
| 7 | + |
| 8 | +## The ResolvedCorrectionProducer class |
| 9 | + |
| 10 | +A quick assist is specified by subclassing the ResolvedCorrectionProducer class. |
| 11 | +Here is our example: |
| 12 | + |
| 13 | +```dart |
| 14 | +import 'package:analysis_server_plugin/edit/dart/correction_producer.dart'; |
| 15 | +import 'package:analyzer/dart/ast/ast.dart'; |
| 16 | +import 'package:analyzer_plugin/utilities/change_builder/change_builder_core.dart'; |
| 17 | +import 'package:analyzer_plugin/utilities/assist/assist.dart'; |
| 18 | +import 'package:analyzer_plugin/utilities/range_factory.dart'; |
| 19 | +
|
| 20 | +class RemoveAwait extends ResolvedCorrectionProducer { |
| 21 | + static const _removeAwaitKind = AssistKind( |
| 22 | + 'dart.assist.removeAwait', 30 /* default */, "Remove the 'await' keyword"); |
| 23 | +
|
| 24 | + RemoveAwait({required super.context}); |
| 25 | +
|
| 26 | + @override |
| 27 | + CorrectionApplicability get applicability => |
| 28 | + CorrectionApplicability.singleLocation; |
| 29 | +
|
| 30 | + @override |
| 31 | + AssistKind get assistKind => _removeAwaitKind; |
| 32 | +
|
| 33 | + @override |
| 34 | + Future<void> compute(ChangeBuilder builder) async { |
| 35 | + var awaitExpression = node; |
| 36 | + if (awaitExpression is AwaitExpression) { |
| 37 | + var awaitToken = awaitExpression.awaitKeyword; |
| 38 | + await builder.addDartFileEdit(file, (builder) { |
| 39 | + builder.addDeletion(range.startStart(awaitToken, awaitToken.next!)); |
| 40 | + }); |
| 41 | + } |
| 42 | + } |
| 43 | +} |
| 44 | +``` |
| 45 | + |
| 46 | +Let's look at each declaration individually: |
| 47 | + |
| 48 | +* `class RemoveAwait` - A quick assist is a class that extends |
| 49 | + `ResolvedCorrectionProducer`. The name of the base class indicates that an |
| 50 | + instance of this class can produce "corrections" (a set of edits) for a |
| 51 | + resolved library. |
| 52 | +* `static const _removeAwaitKind = AssistKind(...)` - Each quick assist must |
| 53 | + have an associated `AssistKind` which has a unique `id` |
| 54 | + (`'dart.assist.removeAwait'`), a priority (`DartFixKindPriority.standard` is a |
| 55 | + fine default), and a message which is displayed in the IDE |
| 56 | + (`"Remove the 'await' keyword"`). |
| 57 | +* `RemoveAwait({required super.context});` - A standard constructor that accepts |
| 58 | + a `CorrectionProducerContext` and passes it up to the super-constructor. |
| 59 | +* `CorrectionApplicability get applicability =>` - the applicability field |
| 60 | + describes how widely an assist can be applied safely and sensibly. Currently, |
| 61 | + only `CorrectionApplicability.singleLocation` should be used. |
| 62 | +* `AssistKind get assistKind => _removeAwaitKind;` - each instance of this class |
| 63 | + can refer to the static field for it's `assistKind`. |
| 64 | +* `Future<void> compute(ChangeBuilder builder)` - This method is called when the |
| 65 | + client has requested quick assists at a specific location, and we want a |
| 66 | + possible correction from this correction producer. This is the code that |
| 67 | + looks at the `node` field and surrounding code and determines what correction |
| 68 | + to offer, if any. |
| 69 | + |
| 70 | + * `await builder.addDartFileEdit(...)` - Once we have determined that we want |
| 71 | + to offer an assist, we call this method, and specify code deletions, |
| 72 | + insertions, and/or replacements inside the callback function. If there are |
| 73 | + cases where this correction producer will not offer any quick assists (such |
| 74 | + as the source code having certain properties), then those cases should be |
| 75 | + checked so that we don't call this method in such cases. |
| 76 | + * `builder.addDeletion(...)` - For this assist (removing an `await` keyword), |
| 77 | + we can use `addDeletion` to specify a range of source code text to delete. |
| 78 | + The `DartFileEditBuilder` class has many utilities for adding various edits. |
| 79 | + |
| 80 | + Writing a quick assist can be non-trivial, even for changes which are |
| 81 | + conceptually simple. It may be helpful to see examples that are similar to a |
| 82 | + desired assist. See the [assists that are offered by Dart Analysis |
| 83 | + Server][existing-assists] for hundreds of examples. |
| 84 | + |
| 85 | +Instances of the correction producer class are short-lived, and they can contain |
| 86 | +state related to the source-code-under-analysis. Indeed, the |
| 87 | +`CorrectionProducerContext`, which is passed into the constructor, and available |
| 88 | +as a field in the super-class, contains information specific to the |
| 89 | +code-under-analysis. |
| 90 | + |
| 91 | +## Registering a quick assist |
| 92 | + |
| 93 | +In order for a quick assist to be used in an analyzer plugin, it must be |
| 94 | +registered. Register the quick assist's constructor inside a plugin's |
| 95 | +`register` method: |
| 96 | + |
| 97 | +```dart |
| 98 | +import 'package:analysis_server_plugin/plugin.dart'; |
| 99 | +import 'package:analysis_server_plugin/registry.dart'; |
| 100 | +
|
| 101 | +final plugin = SimplePlugin(); |
| 102 | +
|
| 103 | +class SimplePlugin extends Plugin { |
| 104 | + @override |
| 105 | + void register(PluginRegistry registry) { |
| 106 | + registry.registerAssist(RemoveAwait.new); |
| 107 | + } |
| 108 | +} |
| 109 | +``` |
| 110 | + |
| 111 | +Instances of correction producers contain state related to the specific |
| 112 | +source-code-under-analysis, which is why the constructor is given here, |
| 113 | +instead of a long-lived instance. |
| 114 | + |
| 115 | +See [writing a plugin][] for information about the `Plugin` class. |
| 116 | + |
| 117 | +[writing rules]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_rules.md |
| 118 | +[existing-assists]: https://github.com/dart-lang/sdk/tree/main/pkg/analysis_server/lib/src/services/correction/dart |
| 119 | +[writing a plugin]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_rules.md |
0 commit comments