OLD | NEW |
1 // Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2015, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 /// Support for client code that wants to consume options contributed to the | 5 /// Support for client code that wants to consume options contributed to the |
6 /// analysis options file. | 6 /// analysis options file. |
7 library analyzer.plugin.options; | 7 library analyzer.plugin.options; |
8 | 8 |
9 import 'package:analyzer/error/listener.dart'; | 9 import 'package:analyzer/error/listener.dart'; |
10 import 'package:analyzer/src/generated/engine.dart'; | |
11 import 'package:analyzer/src/plugin/options_plugin.dart'; | 10 import 'package:analyzer/src/plugin/options_plugin.dart'; |
12 import 'package:plugin/plugin.dart'; | 11 import 'package:plugin/plugin.dart'; |
13 import 'package:yaml/yaml.dart'; | 12 import 'package:yaml/yaml.dart'; |
14 | 13 |
15 /// The identifier of the extension point that allows plugins to access | |
16 /// options defined in the analysis options file. The object used as an | |
17 /// extension must be an [OptionsProcessor]. | |
18 final String OPTIONS_PROCESSOR_EXTENSION_POINT_ID = Plugin.join( | |
19 OptionsPlugin.UNIQUE_IDENTIFIER, | |
20 OptionsPlugin.OPTIONS_PROCESSOR_EXTENSION_POINT); | |
21 | |
22 /// The identifier of the extension point that allows plugins to validate | 14 /// The identifier of the extension point that allows plugins to validate |
23 /// options defined in the analysis options file. The object used as an | 15 /// options defined in the analysis options file. The object used as an |
24 /// extension must be an [OptionsValidator]. | 16 /// extension must be an [OptionsValidator]. |
25 final String OPTIONS_VALIDATOR_EXTENSION_POINT_ID = Plugin.join( | 17 final String OPTIONS_VALIDATOR_EXTENSION_POINT_ID = Plugin.join( |
26 OptionsPlugin.UNIQUE_IDENTIFIER, | 18 OptionsPlugin.UNIQUE_IDENTIFIER, |
27 OptionsPlugin.OPTIONS_VALIDATOR_EXTENSION_POINT); | 19 OptionsPlugin.OPTIONS_VALIDATOR_EXTENSION_POINT); |
28 | 20 |
29 /// Processes options defined in the analysis options file. | 21 /// Validates options as defined in an analysis options file. |
30 /// | |
31 /// Clients may implement this class when implementing plugins. | |
32 /// | 22 /// |
33 /// The options file format is intentionally very open-ended, giving clients | 23 /// The options file format is intentionally very open-ended, giving clients |
34 /// utmost flexibility in defining their own options. The only hardfast | 24 /// utmost flexibility in defining their own options. The only hardfast |
35 /// expectation is that options files will contain a mapping from Strings | 25 /// expectation is that options files will contain a mapping from Strings |
36 /// (identifying 'scopes') to associated options. For example, the given | 26 /// (identifying 'scopes') to associated options. For example, the given |
37 /// content | 27 /// content |
38 /// | 28 /// |
39 /// linter: | 29 /// linter: |
40 /// rules: | 30 /// rules: |
41 /// camel_case_types: true | 31 /// camel_case_types: true |
42 /// compiler: | 32 /// compiler: |
43 /// resolver: | 33 /// resolver: |
44 /// useMultiPackage: true | 34 /// useMultiPackage: true |
45 /// packagePaths: | 35 /// packagePaths: |
46 /// - /foo/bar/pkg | 36 /// - /foo/bar/pkg |
47 /// - /bar/baz/pkg | 37 /// - /bar/baz/pkg |
48 /// | 38 /// |
49 /// defines two scopes, `linter` and `compiler`. Parsing would result in a | 39 /// defines two scopes, `linter` and `compiler`. Parsing would result in a |
50 /// map, mapping the `linter` and `compiler` scope identifiers to their | 40 /// map, mapping the `linter` and `compiler` scope identifiers to their |
51 /// respective parsed option node contents. Extracting values is a simple | 41 /// respective parsed option node contents. Extracting values is a simple |
52 /// matter of inspecting the parsed nodes. For example, testing whether the | 42 /// matter of inspecting the parsed nodes. For example, testing whether the |
53 /// compiler's resolver is set to use the `useMultiPackage` option might look | 43 /// compiler's resolver is set to use the `useMultiPackage` option might look |
54 /// something like this (eliding error-checking): | 44 /// something like this (eliding error-checking): |
55 /// | 45 /// |
56 /// bool useMultiPackage = | 46 /// bool useMultiPackage = |
57 /// options['compiler']['resolver']['useMultiPackage']; | 47 /// options['compiler']['resolver']['useMultiPackage']; |
58 abstract class OptionsProcessor { | |
59 /// Called when an error occurs in processing options. | |
60 void onError(Exception exception); | |
61 | |
62 /// Called when an options file is processed. | |
63 /// | |
64 /// The options file is processed on analyzer initialization and | |
65 /// subsequently when the file is changed on disk. In the event of a | |
66 /// change notification, note that the notification simply indicates | |
67 /// a change on disk. Content in specific option scopes may or may not | |
68 /// be different. It is up to the implementer to check whether specific | |
69 /// options have changed and to handle those changes appropriately. In | |
70 /// addition to the [options] map, the associated analysis [context] is | |
71 /// provided as well to allow for context-specific configuration. | |
72 void optionsProcessed(AnalysisContext context, Map<String, Object> options); | |
73 } | |
74 | |
75 /// Validates options as defined in an analysis options file. | |
76 /// | 48 /// |
77 /// Clients may implement this class when implementing plugins. | 49 /// Clients may implement this class when implementing plugins. |
78 /// | 50 /// |
79 /// See [OptionsProcessor] for a description of the options file format. | |
80 /// | |
81 abstract class OptionsValidator { | 51 abstract class OptionsValidator { |
82 /// Validate [options], reporting any errors to the given [reporter]. | 52 /// Validate [options], reporting any errors to the given [reporter]. |
83 void validate(ErrorReporter reporter, Map<String, YamlNode> options); | 53 void validate(ErrorReporter reporter, Map<String, YamlNode> options); |
84 } | 54 } |
OLD | NEW |