Convert builder.dart to triple-slash comment style
Change-Id: I73e371b073ef2f7448a175b5fdb85bd77d8529a6 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/132460 Reviewed-by: Brian Wilkerson <brianwilkerson@google.com>
This commit is contained in:
Paul Berry
committed by
commit-bot@chromium.org
commit-bot@chromium.org
parent
48aa6470ca
commit
16cb7cee1b
@@ -44,97 +44,71 @@ import 'package:args/args.dart';
|
||||
import 'package:path/src/context.dart';
|
||||
import 'package:yaml/yaml.dart';
|
||||
|
||||
/**
|
||||
* A utility class used to build an analysis context for a given directory.
|
||||
*
|
||||
* The construction of analysis contexts is as follows:
|
||||
*
|
||||
* 1. Determine how package: URI's are to be resolved. This follows the lookup
|
||||
* algorithm defined by the [package specification][1].
|
||||
*
|
||||
* 2. Using the results of step 1, look in each package for an embedder file
|
||||
* (_embedder.yaml). If one exists then it defines the SDK. If multiple such
|
||||
* files exist then use the first one found. Otherwise, use the default SDK.
|
||||
*
|
||||
* 3. Look for an analysis options file (`analysis_options.yaml` or
|
||||
* `.analysis_options`) and process the options in the file.
|
||||
*
|
||||
* 4. Create a new context. Initialize its source factory based on steps 1, 2
|
||||
* and 3. Initialize its analysis options from step 4.
|
||||
*
|
||||
* [1]: https://github.com/dart-lang/dart_enhancement_proposals/blob/master/Accepted/0005%20-%20Package%20Specification/DEP-pkgspec.md.
|
||||
*/
|
||||
/// A utility class used to build an analysis context for a given directory.
|
||||
///
|
||||
/// The construction of analysis contexts is as follows:
|
||||
///
|
||||
/// 1. Determine how package: URI's are to be resolved. This follows the lookup
|
||||
/// algorithm defined by the [package specification][1].
|
||||
///
|
||||
/// 2. Using the results of step 1, look in each package for an embedder file
|
||||
/// (_embedder.yaml). If one exists then it defines the SDK. If multiple such
|
||||
/// files exist then use the first one found. Otherwise, use the default SDK.
|
||||
///
|
||||
/// 3. Look for an analysis options file (`analysis_options.yaml` or
|
||||
/// `.analysis_options`) and process the options in the file.
|
||||
///
|
||||
/// 4. Create a new context. Initialize its source factory based on steps 1, 2
|
||||
/// and 3. Initialize its analysis options from step 4.
|
||||
///
|
||||
/// [1]: https://github.com/dart-lang/dart_enhancement_proposals/blob/master/Accepted/0005%20-%20Package%20Specification/DEP-pkgspec.md.
|
||||
class ContextBuilder {
|
||||
/**
|
||||
* A callback for when analysis drivers are created, which takes all the same
|
||||
* arguments as the dart analysis driver constructor so that plugins may
|
||||
* create their own drivers with the same tools, in theory. Here as a stopgap
|
||||
* until the official plugin API is complete
|
||||
*/
|
||||
/// A callback for when analysis drivers are created, which takes all the same
|
||||
/// arguments as the dart analysis driver constructor so that plugins may
|
||||
/// create their own drivers with the same tools, in theory. Here as a stopgap
|
||||
/// until the official plugin API is complete
|
||||
static Function onCreateAnalysisDriver;
|
||||
|
||||
/**
|
||||
* The [ResourceProvider] by which paths are converted into [Resource]s.
|
||||
*/
|
||||
/// The [ResourceProvider] by which paths are converted into [Resource]s.
|
||||
final ResourceProvider resourceProvider;
|
||||
|
||||
/**
|
||||
* The manager used to manage the DartSdk's that have been created so that
|
||||
* they can be shared across contexts.
|
||||
*/
|
||||
/// The manager used to manage the DartSdk's that have been created so that
|
||||
/// they can be shared across contexts.
|
||||
final DartSdkManager sdkManager;
|
||||
|
||||
/**
|
||||
* The cache containing the contents of overlaid files. If this builder will
|
||||
* be used to build analysis drivers, set the [fileContentOverlay] instead.
|
||||
*/
|
||||
/// The cache containing the contents of overlaid files. If this builder will
|
||||
/// be used to build analysis drivers, set the [fileContentOverlay] instead.
|
||||
final ContentCache contentCache;
|
||||
|
||||
/**
|
||||
* The options used by the context builder.
|
||||
*/
|
||||
/// The options used by the context builder.
|
||||
final ContextBuilderOptions builderOptions;
|
||||
|
||||
/**
|
||||
* The scheduler used by any analysis drivers created through this interface.
|
||||
*/
|
||||
/// The scheduler used by any analysis drivers created through this interface.
|
||||
AnalysisDriverScheduler analysisDriverScheduler;
|
||||
|
||||
/**
|
||||
* The performance log used by any analysis drivers created through this
|
||||
* interface.
|
||||
*/
|
||||
/// The performance log used by any analysis drivers created through this
|
||||
/// interface.
|
||||
PerformanceLog performanceLog;
|
||||
|
||||
/**
|
||||
* The byte store used by any analysis drivers created through this interface.
|
||||
*/
|
||||
/// The byte store used by any analysis drivers created through this interface.
|
||||
ByteStore byteStore;
|
||||
|
||||
/**
|
||||
* The file content overlay used by analysis drivers. If this builder will be
|
||||
* used to build analysis contexts, set the [contentCache] instead.
|
||||
*/
|
||||
/// The file content overlay used by analysis drivers. If this builder will be
|
||||
/// used to build analysis contexts, set the [contentCache] instead.
|
||||
FileContentOverlay fileContentOverlay;
|
||||
|
||||
/**
|
||||
* Whether any analysis driver created through this interface should support
|
||||
* indexing and search.
|
||||
*/
|
||||
/// Whether any analysis driver created through this interface should support
|
||||
/// indexing and search.
|
||||
bool enableIndex = false;
|
||||
|
||||
/**
|
||||
* Initialize a newly created builder to be ready to build a context rooted in
|
||||
* the directory with the given [rootDirectoryPath].
|
||||
*/
|
||||
/// Initialize a newly created builder to be ready to build a context rooted in
|
||||
/// the directory with the given [rootDirectoryPath].
|
||||
ContextBuilder(this.resourceProvider, this.sdkManager, this.contentCache,
|
||||
{ContextBuilderOptions options})
|
||||
: builderOptions = options ?? ContextBuilderOptions();
|
||||
|
||||
/**
|
||||
* Return an analysis driver that is configured correctly to analyze code in
|
||||
* the directory with the given [path].
|
||||
*/
|
||||
/// Return an analysis driver that is configured correctly to analyze code in
|
||||
/// the directory with the given [path].
|
||||
AnalysisDriver buildDriver(ContextRoot contextRoot) {
|
||||
String path = contextRoot.root;
|
||||
AnalysisOptions options =
|
||||
@@ -180,9 +154,7 @@ class ContextBuilder {
|
||||
return driver;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return an analysis options object containing the default option values.
|
||||
*/
|
||||
/// Return an analysis options object containing the default option values.
|
||||
AnalysisOptions createDefaultOptions() {
|
||||
AnalysisOptions defaultOptions = builderOptions.defaultOptions;
|
||||
if (defaultOptions == null) {
|
||||
@@ -239,10 +211,8 @@ class ContextBuilder {
|
||||
return workspace.createSourceFactory(sdk, summaryData);
|
||||
}
|
||||
|
||||
/**
|
||||
* Add any [declaredVariables] to the list of declared variables used by the
|
||||
* given analysis [driver].
|
||||
*/
|
||||
/// Add any [declaredVariables] to the list of declared variables used by the
|
||||
/// given analysis [driver].
|
||||
void declareVariablesInDriver(AnalysisDriver driver) {
|
||||
Map<String, String> variables = builderOptions.declaredVariables;
|
||||
if (variables != null && variables.isNotEmpty) {
|
||||
@@ -251,16 +221,14 @@ class ContextBuilder {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Finds a package resolution strategy for the directory at the given absolute
|
||||
* [path].
|
||||
*
|
||||
* This function first tries to locate a `.packages` file in the directory. If
|
||||
* that is not found, it instead checks for the presence of a `packages/`
|
||||
* directory in the same place. If that also fails, it starts checking parent
|
||||
* directories for a `.packages` file, and stops if it finds it. Otherwise it
|
||||
* gives up and returns [Packages.empty].
|
||||
*/
|
||||
/// Finds a package resolution strategy for the directory at the given absolute
|
||||
/// [path].
|
||||
///
|
||||
/// This function first tries to locate a `.packages` file in the directory. If
|
||||
/// that is not found, it instead checks for the presence of a `packages/`
|
||||
/// directory in the same place. If that also fails, it starts checking parent
|
||||
/// directories for a `.packages` file, and stops if it finds it. Otherwise it
|
||||
/// gives up and returns [Packages.empty].
|
||||
Packages findPackagesFromFile(String path) {
|
||||
Resource location = _findPackagesLocation(path);
|
||||
if (location is File) {
|
||||
@@ -275,12 +243,10 @@ class ContextBuilder {
|
||||
return Packages.empty;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the SDK that should be used to analyze code. Use the given
|
||||
* [workspace] and [analysisOptions] to locate the SDK.
|
||||
*
|
||||
* TODO(scheglov) Remove [analysisOptions]?
|
||||
*/
|
||||
/// Return the SDK that should be used to analyze code. Use the given
|
||||
/// [workspace] and [analysisOptions] to locate the SDK.
|
||||
///
|
||||
/// TODO(scheglov) Remove [analysisOptions]?
|
||||
DartSdk findSdk(Workspace workspace, AnalysisOptions analysisOptions) {
|
||||
String summaryPath = builderOptions.dartSdkSummaryPath;
|
||||
if (summaryPath != null) {
|
||||
@@ -399,14 +365,12 @@ class ContextBuilder {
|
||||
return options;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the analysis options file that should be used when analyzing code in
|
||||
* the directory with the given [path].
|
||||
*
|
||||
* If [forceSearch] is true, then don't return the default analysis options
|
||||
* path. This allows cli to locate what *would* have been the analysis options
|
||||
* file path, and super-impose the defaults over it in-place.
|
||||
*/
|
||||
/// Return the analysis options file that should be used when analyzing code in
|
||||
/// the directory with the given [path].
|
||||
///
|
||||
/// If [forceSearch] is true, then don't return the default analysis options
|
||||
/// path. This allows cli to locate what *would* have been the analysis options
|
||||
/// file path, and super-impose the defaults over it in-place.
|
||||
File getOptionsFile(String path, {bool forceSearch = false}) {
|
||||
if (!forceSearch) {
|
||||
String filePath = builderOptions.defaultAnalysisOptionsFilePath;
|
||||
@@ -430,14 +394,12 @@ class ContextBuilder {
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a [Packages] object for a 'package' directory ([folder]).
|
||||
*
|
||||
* Package names are resolved as relative to sub-directories of the package
|
||||
* directory.
|
||||
*
|
||||
* TODO(scheglov) Remove this feature
|
||||
*/
|
||||
/// Create a [Packages] object for a 'package' directory ([folder]).
|
||||
///
|
||||
/// Package names are resolved as relative to sub-directories of the package
|
||||
/// directory.
|
||||
///
|
||||
/// TODO(scheglov) Remove this feature
|
||||
Packages getPackagesFromFolder(Folder folder) {
|
||||
Context pathContext = resourceProvider.pathContext;
|
||||
var map = <String, Package>{};
|
||||
@@ -460,9 +422,7 @@ class ContextBuilder {
|
||||
return Packages(map);
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve any symbolic links encoded in the path to the given [folder].
|
||||
*/
|
||||
/// Resolve any symbolic links encoded in the path to the given [folder].
|
||||
String resolveSymbolicLink(Folder folder) {
|
||||
try {
|
||||
return folder.resolveSymbolicLinksSync().path;
|
||||
@@ -471,10 +431,8 @@ class ContextBuilder {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve any symbolic links encoded in the URI's in the given [map] by
|
||||
* replacing the values in the map.
|
||||
*/
|
||||
/// Resolve any symbolic links encoded in the URI's in the given [map] by
|
||||
/// replacing the values in the map.
|
||||
void resolveSymbolicLinks(Map<String, Uri> map) {
|
||||
Context pathContext = resourceProvider.pathContext;
|
||||
for (String packageName in map.keys) {
|
||||
@@ -489,19 +447,17 @@ class ContextBuilder {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Find the location of the package resolution file/directory for the
|
||||
* directory at the given absolute [path].
|
||||
*
|
||||
* Checks for a `.packages` file in the [path]. If not found,
|
||||
* checks for a `packages` directory in the same directory. If still not
|
||||
* found, starts checking parent directories for `.packages` until reaching
|
||||
* the root directory.
|
||||
*
|
||||
* Return a [File] object representing a `.packages` file if one is found, a
|
||||
* [Folder] object for the `packages/` directory if that is found, or `null`
|
||||
* if neither is found.
|
||||
*/
|
||||
/// Find the location of the package resolution file/directory for the
|
||||
/// directory at the given absolute [path].
|
||||
///
|
||||
/// Checks for a `.packages` file in the [path]. If not found,
|
||||
/// checks for a `packages` directory in the same directory. If still not
|
||||
/// found, starts checking parent directories for `.packages` until reaching
|
||||
/// the root directory.
|
||||
///
|
||||
/// Return a [File] object representing a `.packages` file if one is found, a
|
||||
/// [Folder] object for the `packages/` directory if that is found, or `null`
|
||||
/// if neither is found.
|
||||
Resource _findPackagesLocation(String path) {
|
||||
var resource = resourceProvider.getResource(path);
|
||||
while (resource != null) {
|
||||
@@ -521,10 +477,8 @@ class ContextBuilder {
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return the `pubspec.yaml` file that should be used when analyzing code in
|
||||
* the directory with the given [path], possibly `null`.
|
||||
*/
|
||||
/// Return the `pubspec.yaml` file that should be used when analyzing code in
|
||||
/// the directory with the given [path], possibly `null`.
|
||||
File _findPubspecFile(String path) {
|
||||
var resource = resourceProvider.getResource(path);
|
||||
while (resource != null) {
|
||||
@@ -565,10 +519,8 @@ class ContextBuilder {
|
||||
return workspace;
|
||||
}
|
||||
|
||||
/**
|
||||
* Return `true` if either the directory at [rootPath] or a parent of that
|
||||
* directory contains a `.packages` file.
|
||||
*/
|
||||
/// Return `true` if either the directory at [rootPath] or a parent of that
|
||||
/// directory contains a `.packages` file.
|
||||
static bool _hasPackageFileInPath(
|
||||
ResourceProvider resourceProvider, String rootPath) {
|
||||
Folder folder = resourceProvider.getFolder(rootPath);
|
||||
@@ -583,113 +535,79 @@ class ContextBuilder {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Options used by a [ContextBuilder].
|
||||
*/
|
||||
/// Options used by a [ContextBuilder].
|
||||
class ContextBuilderOptions {
|
||||
/**
|
||||
* The results of parsing the command line arguments as defined by
|
||||
* [defineAnalysisArguments] or `null` if none.
|
||||
*/
|
||||
/// The results of parsing the command line arguments as defined by
|
||||
/// [defineAnalysisArguments] or `null` if none.
|
||||
ArgResults argResults;
|
||||
|
||||
/**
|
||||
* The file path of the file containing the summary of the SDK that should be
|
||||
* used to "analyze" the SDK. This option should only be specified by
|
||||
* command-line tools such as 'dartanalyzer' or 'ddc'.
|
||||
*/
|
||||
/// The file path of the file containing the summary of the SDK that should be
|
||||
/// used to "analyze" the SDK. This option should only be specified by
|
||||
/// command-line tools such as 'dartanalyzer' or 'ddc'.
|
||||
String dartSdkSummaryPath;
|
||||
|
||||
/**
|
||||
* The file path of the analysis options file that should be used in place of
|
||||
* any file in the root directory or a parent of the root directory, or `null`
|
||||
* if the normal lookup mechanism should be used.
|
||||
*/
|
||||
/// The file path of the analysis options file that should be used in place of
|
||||
/// any file in the root directory or a parent of the root directory, or `null`
|
||||
/// if the normal lookup mechanism should be used.
|
||||
String defaultAnalysisOptionsFilePath;
|
||||
|
||||
/**
|
||||
* A table mapping variable names to values for the declared variables, or
|
||||
* `null` if no additional variables should be declared.
|
||||
*/
|
||||
/// A table mapping variable names to values for the declared variables, or
|
||||
/// `null` if no additional variables should be declared.
|
||||
Map<String, String> declaredVariables;
|
||||
|
||||
/**
|
||||
* The default analysis options that should be used unless some or all of them
|
||||
* are overridden in the analysis options file, or `null` if the default
|
||||
* defaults should be used.
|
||||
*/
|
||||
/// The default analysis options that should be used unless some or all of them
|
||||
/// are overridden in the analysis options file, or `null` if the default
|
||||
/// defaults should be used.
|
||||
AnalysisOptions defaultOptions;
|
||||
|
||||
/**
|
||||
* The file path of the .packages file that should be used in place of any
|
||||
* file found using the normal (Package Specification DEP) lookup mechanism,
|
||||
* or `null` if the normal lookup mechanism should be used.
|
||||
*/
|
||||
/// The file path of the .packages file that should be used in place of any
|
||||
/// file found using the normal (Package Specification DEP) lookup mechanism,
|
||||
/// or `null` if the normal lookup mechanism should be used.
|
||||
String defaultPackageFilePath;
|
||||
|
||||
/**
|
||||
* The file path of the packages directory that should be used in place of any
|
||||
* file found using the normal (Package Specification DEP) lookup mechanism,
|
||||
* or `null` if the normal lookup mechanism should be used.
|
||||
*/
|
||||
/// The file path of the packages directory that should be used in place of any
|
||||
/// file found using the normal (Package Specification DEP) lookup mechanism,
|
||||
/// or `null` if the normal lookup mechanism should be used.
|
||||
String defaultPackagesDirectoryPath;
|
||||
|
||||
/**
|
||||
* A list of the paths of summary files that are to be used, or `null` if no
|
||||
* summary information is available.
|
||||
*/
|
||||
/// A list of the paths of summary files that are to be used, or `null` if no
|
||||
/// summary information is available.
|
||||
List<String> librarySummaryPaths;
|
||||
|
||||
/**
|
||||
* Initialize a newly created set of options
|
||||
*/
|
||||
/// Initialize a newly created set of options
|
||||
ContextBuilderOptions();
|
||||
}
|
||||
|
||||
/**
|
||||
* Given a package map, check in each package's lib directory for the existence
|
||||
* of an `_embedder.yaml` file. If the file contains a top level YamlMap, it
|
||||
* will be added to the [embedderYamls] map.
|
||||
*/
|
||||
/// Given a package map, check in each package's lib directory for the existence
|
||||
/// of an `_embedder.yaml` file. If the file contains a top level YamlMap, it
|
||||
/// will be added to the [embedderYamls] map.
|
||||
class EmbedderYamlLocator {
|
||||
/**
|
||||
* The name of the embedder files being searched for.
|
||||
*/
|
||||
/// The name of the embedder files being searched for.
|
||||
static const String EMBEDDER_FILE_NAME = '_embedder.yaml';
|
||||
|
||||
/**
|
||||
* A mapping from a package's library directory to the parsed YamlMap.
|
||||
*/
|
||||
/// A mapping from a package's library directory to the parsed YamlMap.
|
||||
final Map<Folder, YamlMap> embedderYamls = HashMap<Folder, YamlMap>();
|
||||
|
||||
/**
|
||||
* Initialize a newly created locator by processing the packages in the given
|
||||
* [packageMap].
|
||||
*/
|
||||
/// Initialize a newly created locator by processing the packages in the given
|
||||
/// [packageMap].
|
||||
EmbedderYamlLocator(Map<String, List<Folder>> packageMap) {
|
||||
if (packageMap != null) {
|
||||
_processPackageMap(packageMap);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Initialize with the given [libFolder] of `sky_engine` package.
|
||||
*/
|
||||
/// Initialize with the given [libFolder] of `sky_engine` package.
|
||||
EmbedderYamlLocator.forLibFolder(Folder libFolder) {
|
||||
_processPackage([libFolder]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Programmatically add an `_embedder.yaml` mapping.
|
||||
*/
|
||||
/// Programmatically add an `_embedder.yaml` mapping.
|
||||
void addEmbedderYaml(Folder libDir, String embedderYaml) {
|
||||
_processEmbedderYaml(libDir, embedderYaml);
|
||||
}
|
||||
|
||||
/**
|
||||
* Refresh the map of located files to those found by processing the given
|
||||
* [packageMap].
|
||||
*/
|
||||
/// Refresh the map of located files to those found by processing the given
|
||||
/// [packageMap].
|
||||
void refresh(Map<String, List<Folder>> packageMap) {
|
||||
// Clear existing.
|
||||
embedderYamls.clear();
|
||||
@@ -698,10 +616,8 @@ class EmbedderYamlLocator {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Given the yaml for an embedder ([embedderYaml]) and a folder ([libDir]),
|
||||
* setup the uri mapping.
|
||||
*/
|
||||
/// Given the yaml for an embedder ([embedderYaml]) and a folder ([libDir]),
|
||||
/// setup the uri mapping.
|
||||
void _processEmbedderYaml(Folder libDir, String embedderYaml) {
|
||||
try {
|
||||
YamlNode yaml = loadYaml(embedderYaml);
|
||||
@@ -713,10 +629,8 @@ class EmbedderYamlLocator {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Given a package list of folders ([libDirs]), process any
|
||||
* `_embedder.yaml` files that are found in any of the folders.
|
||||
*/
|
||||
/// Given a package list of folders ([libDirs]), process any
|
||||
/// `_embedder.yaml` files that are found in any of the folders.
|
||||
void _processPackage(List<Folder> libDirs) {
|
||||
for (Folder libDir in libDirs) {
|
||||
String embedderYaml = _readEmbedderYaml(libDir);
|
||||
@@ -726,17 +640,13 @@ class EmbedderYamlLocator {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Process each of the entries in the [packageMap].
|
||||
*/
|
||||
/// Process each of the entries in the [packageMap].
|
||||
void _processPackageMap(Map<String, List<Folder>> packageMap) {
|
||||
packageMap.values.forEach(_processPackage);
|
||||
}
|
||||
|
||||
/**
|
||||
* Read and return the contents of [libDir]/[EMBEDDER_FILE_NAME], or `null` if
|
||||
* the file doesn't exist.
|
||||
*/
|
||||
/// Read and return the contents of [libDir]/[EMBEDDER_FILE_NAME], or `null` if
|
||||
/// the file doesn't exist.
|
||||
String _readEmbedderYaml(Folder libDir) {
|
||||
File file = libDir.getChild(EMBEDDER_FILE_NAME);
|
||||
try {
|
||||
|
||||
Reference in New Issue
Block a user