// 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.

import 'dart:async';

import 'package:analyzer/dart/analysis/results.dart';
import 'package:analyzer/file_system/file_system.dart';
import 'package:analyzer/src/generated/source.dart';
import 'package:analyzer_plugin/protocol/protocol_common.dart';

/// [AbortCompletion] is thrown when the current completion request
/// should be aborted because either
/// the source changed since the request was made, or
/// a new completion request was received.
class AbortCompletion {}

/// An object used to produce completions at a specific location within a file.
///
/// Clients may implement this class when implementing plugins.
abstract class CompletionContributor {
  /// Return a [Future] that completes with a list of suggestions
  /// for the given completion [request]. This will
  /// throw [AbortCompletion] if the completion request has been aborted.
  Future<List<CompletionSuggestion>> computeSuggestions(
      CompletionRequest request);
}

/// The information about a requested list of completions.
///
/// Clients may not extend, implement or mix-in this class.
abstract class CompletionRequest {
  /// Return the offset within the source at which the completion is being
  /// requested.
  int get offset;

  /// Return the resource provider associated with this request.
  ResourceProvider get resourceProvider;

  /// The analysis result for the file in which the completion is being
  /// requested.
  ResolvedUnitResult get result;

  /// Return the source in which the completion is being requested.
  Source get source;

  /// Return the content of the [source] in which the completion is being
  /// requested, or `null` if the content could not be accessed.
  String get sourceContents;

  /// Return `true` if the new relevance computations should be used when
  /// computing code completion suggestions.
  bool get useNewRelevance;

  /// Throw [AbortCompletion] if the completion request has been aborted.
  void checkAborted();
}