next step toward completion plugin API

pkg/analysis_server/lib/src/provisional/completion/completion_dart.dart

 // Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 library analysis_server.src.provisional.completion.completion_dart;
 
+import 'dart:async';
+
 import 'package:analysis_server/plugin/protocol/protocol.dart';
 import 'package:analysis_server/src/provisional/completion/completion_core.dart';
 import 'package:analysis_server/src/provisional/completion/dart/completion_target.dart';
+import 'package:analysis_server/src/services/completion/dart_completion_manager.dart'
+    show DART_RELEVANCE_DEFAULT;
 import 'package:analyzer/src/generated/ast.dart';
-import 'package:analyzer/src/generated/engine.dart';
-import 'package:analyzer/src/generated/source.dart';
+import 'package:analyzer/src/generated/element.dart' as model;
+import 'package:analyzer/task/model.dart';
 
 /**
- * An object used to produce completions for a specific error within a Dart
- * file. Completion contributors are long-lived objects and must not retain any
- * state between invocations of [computeSuggestions].
+ * An object used to produce completions within a Dart file.

[Brian Wilkerson, 2015/10/19 23:15:46]

"completions within" --> "completions at a specific location within"

[danrubel, 2015/10/20 00:11:17]

Done.

+ * Contributors are long-lived objects and must not retain any state.

[Brian Wilkerson, 2015/10/19 23:15:46]

I think with the introduction of futures, they're not just long-lived, they are
required to be re-entrant (in which case we should say so).

[danrubel, 2015/10/20 00:11:17]

Done.

  *
  * Clients may extend this class when implementing plugins.
  */
-abstract class DartCompletionContributor implements CompletionContributor {
-  @override
-  List<CompletionSuggestion> computeSuggestions(CompletionRequest request) {
-    if (request is DartCompletionRequest) {
-      return internalComputeSuggestions(request);
-    }
-    AnalysisContext context = request.context;
-    Source source = request.source;
-    List<Source> libraries = context.getLibrariesContaining(source);
-    if (libraries.length < 1) {
-      return null;
-    }
-//    CompilationUnit unit =
-//        context.getResolvedCompilationUnit2(source, libraries[0]);
-//    bool isResolved = true;
-//    if (unit == null) {
-//      // TODO(brianwilkerson) Implement a method for getting a parsed
-//      // compilation unit without parsing the unit if it hasn't been parsed.
-//      unit = context.getParsedCompilationUnit(source);
-//      if (unit == null) {
-//        return null;
-//      }
-//      isResolved = false;
-//    }
-//    DartCompletionRequest dartRequest =
-//        new DartCompletionRequestImpl(request, unit, isResolved);
-//    return internalComputeSuggestions(dartRequest);
-    return null;
-  }
-
+abstract class DartCompletionContributor {
   /**
-   * Compute a list of completion suggestions based on the given completion
-   * [request]. Return the suggestions that were computed.
+   * Compute completion suggestions based upon the given completion [request]
+   * to the given completion [collector].
+   * Return a [Future] that completes when suggestions have been added
+   * or `null` if any suggestions to be added have been added
+   * when the method returns.
    */
-  List<CompletionSuggestion> internalComputeSuggestions(
-      DartCompletionRequest request);
+  Future computeSuggestions(
+      DartCompletionRequest request, DartSuggestionCollector collector);
 }
 
 /**
  * The information about a requested list of completions within a Dart file.
  *
  * Clients may not extend, implement or mix-in this class.
  */
 abstract class DartCompletionRequest extends CompletionRequest {
   /**
-   * Return `true` if the compilation [unit] is resolved.
+   * Return the parsed completion target.  This determines
+   * what part of the parse tree will receive the newly inserted text.
+   * Use [resolvedDeclarationTarget] to obtain a resolved completion target.
    */
-  bool get isResolved;
+  CompletionTarget get parsedTarget;
 
-  /**
-   * Return the completion target.  This determines what part of the parse tree
-   * will receive the newly inserted text.
-   */
+  @deprecated // Use parsedTarget
   CompletionTarget get target;
 
-  /**
-   * Cached information from a prior code completion operation.
-   */
-  //DartCompletionCache get cache;
-
-  /**
-   * Return the compilation unit in which the completion was requested.
-   */
+  @deprecated // Use parsedTarget.unit or resolvedTarget(...).unit

[Brian Wilkerson, 2015/10/19 23:15:46]

"resolvedTarget(...)" --> "resolvedDeclarationTarget"

[danrubel, 2015/10/20 00:11:17]

Done.

   CompilationUnit get unit;
 
   /**
-   * Information about the types of suggestions that should be included.
+   * Return partially resolved completion target where each declarations
+   * in the compilation unit has been bound to corresponding element.
+   * More specifically:
+   *
+   * * The [SimpleIdentifier]s at all declaration sites have been bound
+   * to the element defined by the declaration,
+   * including the constants defined in an 'enum' declaration.
+   * * The types associated with declarations have been resolved, including
+   * the types of superclasses, mixins, interfaces, fields, return types,
+   * parameters, and local variables.
+   * * Directives 'library', 'part' and 'part of' are resolved.
+   * * Imports, exports, publicNamespace, entryPoint,
+   * and exportNamespace are set.
    */
-  //OpType get _optype;
+  Future<CompletionTarget> get resolvedDeclarationTarget;
 }
+
+/**
+ * An object used to collect suggestions.
+ *
+ * Clients should not extend, implement, or instantiate this class.
+ */
+abstract class DartSuggestionCollector {
+  /**
+   * Add a suggestion.
+   */
+  void addCompletionSuggestion(CompletionSuggestion suggestion);
+
+  /**
+   * Add a suggestion based upon the given element.
+   */
+  void addElementSuggestion(model.Element element,
+      {bool includePrivateElements: false,
+      String prefix,
+      int relevance: DART_RELEVANCE_DEFAULT});
+}