Initial work on refactorings.

pkg/analysis_services/lib/correction/status.dart

+// Copyright (c) 2014, 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.
+
+// This code was auto-generated, is not intended to be edited, and is subject to
+// significant change. Please see the README file for more information.
+
+library services.status;
+
+import 'package:analysis_services/search/search_engine.dart';
+import 'package:analysis_services/src/correction/source_range.dart';
+import 'package:analyzer/src/generated/ast.dart';
+import 'package:analyzer/src/generated/element.dart';
+import 'package:analyzer/src/generated/engine.dart';
+import 'package:analyzer/src/generated/java_core.dart';
+import 'package:analyzer/src/generated/source.dart';
+
+
+/**
+ * An outcome of a condition checking operation.
+ */
+class RefactoringStatus {
+  /**
+   * The current severity of this [RefactoringStatus] - the maximum of the
+   * severities of its [entries].
+   */
+  RefactoringStatusSeverity _severity = RefactoringStatusSeverity.OK;
+
+  /**
+   * A list of [RefactoringStatusEntry]s.
+   */
+  final List<RefactoringStatusEntry> entries = [];
+
+  /**
+   * Creates a new OK [RefactoringStatus].
+   */
+  RefactoringStatus();
+
+  /**
+   * Creates a new [RefactoringStatus] with the ERROR severity.
+   */
+  factory RefactoringStatus.error(String msg,
+      [RefactoringStatusContext context]) {
+    RefactoringStatus status = new RefactoringStatus();
+    status.addError(msg, context);
+    return status;
+  }
+
+  /**
+   * Creates a new [RefactoringStatus] with the FATAL severity.
+   */
+  factory RefactoringStatus.fatal(String msg,
+      [RefactoringStatusContext context]) {
+    RefactoringStatus status = new RefactoringStatus();
+    status.addFatalError(msg, context);
+    return status;
+  }
+
+  /**
+   * Creates a new [RefactoringStatus] with the WARNING severity.
+   */
+  factory RefactoringStatus.warning(String msg,
+      [RefactoringStatusContext context]) {
+    RefactoringStatus status = new RefactoringStatus();
+    status.addWarning(msg, context);
+    return status;
+  }
+
+  /**
+   * Returns the [RefactoringStatusEntry] with the highest severity, or `null`

[Brian Wilkerson, 2014/08/11 18:45:29]

"the [" --> "the first ["? (There could be more than one. The alternative, if
order isn't significant, would be "Return a [" and then add "If there is more
than one entry with the highest severity then there is no guarantee as to which
will be returned."

[scheglov, 2014/08/11 18:58:20]

Done.

+   * if no entries.
+   */
+  RefactoringStatusEntry get entryWithHighestSeverity {
+    for (RefactoringStatusEntry entry in entries) {
+      if (entry.severity == _severity) {
+        return entry;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Returns `true` if the severity is FATAL or ERROR.
+   */
+  bool get hasError =>
+      _severity == RefactoringStatusSeverity.FATAL ||
+          _severity == RefactoringStatusSeverity.ERROR;
+
+  /**
+   * Returns `true` if the severity is FATAL.
+   */
+  bool get hasFatalError => _severity == RefactoringStatusSeverity.FATAL;
+
+  /**
+   * Returns `true` if the severity is WARNING.
+   */
+  bool get hasWarning => _severity == RefactoringStatusSeverity.WARNING;
+
+  /**
+   * Return `true` if the severity is `OK`.
+   */
+  bool get isOK => _severity == RefactoringStatusSeverity.OK;
+
+  /**
+   * Returns the message of the [RefactoringStatusEntry] with highest severity;
+   * may be `null` if no entries.
+   */
+  String get message {
+    RefactoringStatusEntry entry = entryWithHighestSeverity;
+    if (entry == null) {
+      return null;
+    }
+    return entry.message;
+  }
+
+  /**
+   * Returns the current severity of this [RefactoringStatus].
+   */
+  RefactoringStatusSeverity get severity => _severity;
+
+  /**
+   * Adds an ERROR entry with the given message and status.
+   */
+  void addError(String msg, [RefactoringStatusContext context]) {
+    _addEntry(
+        new RefactoringStatusEntry(RefactoringStatusSeverity.ERROR, msg, context));
+  }
+
+  /**
+   * Adds a FATAL entry with the given message and status.
+   */
+  void addFatalError(String msg, [RefactoringStatusContext context]) {
+    _addEntry(
+        new RefactoringStatusEntry(RefactoringStatusSeverity.FATAL, msg, context));
+  }
+
+  /**
+   * Merges [other] into this [RefactoringStatus].
+   *
+   * The [other]'s entries are added to this.
+   *
+   * The resulting severity is the more severe of this and [other] severities.
+   *
+   * Merging with `null` is allowed - it has no effect.
+   */
+  void addStatus(RefactoringStatus other) {
+    if (other == null) {
+      return;
+    }
+    entries.addAll(other.entries);
+    _severity = RefactoringStatusSeverity._max(_severity, other.severity);
+  }
+
+  /**
+   * Adds a WARNING entry with the given message and status.
+   */
+  void addWarning(String msg, [RefactoringStatusContext context]) {
+    _addEntry(
+        new RefactoringStatusEntry(RefactoringStatusSeverity.WARNING, msg, context));
+  }
+
+  /**
+   * Returns a copy of this [RefactoringStatus] with ERROR replaced with FATAL.
+   */
+  RefactoringStatus escalateErrorToFatal() {
+    RefactoringStatus result = new RefactoringStatus();
+    for (RefactoringStatusEntry entry in entries) {
+      if (entry.severity == RefactoringStatusSeverity.ERROR) {
+        entry = new RefactoringStatusEntry(
+            RefactoringStatusSeverity.FATAL,
+            entry.message,
+            entry.context);
+      }
+      result._addEntry(entry);
+    }
+    return result;
+  }
+
+  @override
+  String toString() {
+    StringBuffer sb = new StringBuffer();
+    sb.write("<");
+    sb.write(_severity.name);
+    if (!isOK) {
+      sb.write("\n");
+      for (RefactoringStatusEntry entry in entries) {
+        sb.write("\t");
+        sb.write(entry);
+        sb.write("\n");
+      }
+    }
+    sb.write(">");
+    return sb.toString();
+  }
+
+  /**
+   * Adds the given [RefactoringStatusEntry] and updates [severity].
+   */
+  void _addEntry(RefactoringStatusEntry entry) {
+    entries.add(entry);
+    _severity = RefactoringStatusSeverity._max(_severity, entry.severity);
+  }
+}
+
+
+/**
+ * [RefactoringStatusContext] can be used to annotate [RefactoringStatusEntry]s
+ * with additional information typically presented in the user interface.
+ */
+class RefactoringStatusContext {
+  /**
+   * The [AnalysisContext] in which this status occurs.
+   */
+  final AnalysisContext context;
+
+  /**
+   * The [Source] in which this status occurs.
+   */
+  final Source source;
+
+  /**
+   * The [SourceRange] with specific location where this status occurs.
+   */
+  final SourceRange range;
+
+  /**
+   * Creates a new [RefactoringStatusContext].
+   */
+  RefactoringStatusContext(this.context, this.source, this.range);
+
+  /**
+   * Creates a new [RefactoringStatusContext] for the given [Element].
+   */
+  factory RefactoringStatusContext.forElement(Element element) {
+    AnalysisContext context = element.context;
+    Source source = element.source;
+    SourceRange range = rangeElementName(element);
+    return new RefactoringStatusContext(context, source, range);
+  }
+
+  /**
+   * Creates a new [RefactoringStatusContext] for the given [SearchMatch].
+   */
+  factory RefactoringStatusContext.forMatch(SearchMatch match) {
+    Element enclosingElement = match.element;
+    return new RefactoringStatusContext(
+        enclosingElement.context,
+        enclosingElement.source,
+        match.sourceRange);
+  }
+
+  /**
+   * Creates a new [RefactoringStatusContext] for the given [AstNode].
+   */
+  factory RefactoringStatusContext.forNode(AstNode node) {
+    CompilationUnit unit = node.getAncestor((node) => node is CompilationUnit);
+    CompilationUnitElement unitElement = unit.element;
+    AnalysisContext context = unitElement.context;
+    Source source = unitElement.source;
+    SourceRange range = rangeNode(node);
+    return new RefactoringStatusContext(context, source, range);
+  }
+
+  /**
+   * Creates a new [RefactoringStatusContext] for the given [CompilationUnit].
+   */
+  factory RefactoringStatusContext.forUnit(CompilationUnit unit,
+      SourceRange range) {
+    CompilationUnitElement unitElement = unit.element;
+    AnalysisContext context = unitElement.context;
+    Source source = unitElement.source;
+    return new RefactoringStatusContext(context, source, range);
+  }
+
+  @override
+  String toString() {
+    JavaStringBuilder builder = new JavaStringBuilder();
+    builder.append("[source=");
+    builder.append(source);
+    builder.append(", range=");
+    builder.append(range);
+    builder.append("]");
+    return builder.toString();
+  }
+}
+
+
+/**
+ * An immutable object representing an entry in a [RefactoringStatus].
+ *
+ * A [RefactoringStatusEntry] consists of a severity, a message and a context.
+ */
+class RefactoringStatusEntry {
+  /**
+   * The severity level.
+   */
+  final RefactoringStatusSeverity severity;
+
+  /**
+   * The message of the status entry.
+   */
+  final String message;
+
+  /**
+   * The [RefactoringStatusContext] which can be used to show more detailed
+   * information regarding this status entry in the UI.
+   *
+   * May be `null` indicating that no context is available.
+   */
+  final RefactoringStatusContext context;
+
+  RefactoringStatusEntry(this.severity, this.message, [this.context]);
+
+  /**
+   * Returns whether the entry represents an error or not.
+   */
+  bool get isError => severity == RefactoringStatusSeverity.ERROR;
+
+  /**
+   * Returns whether the entry represents a fatal error or not.
+   */
+  bool get isFatalError => severity == RefactoringStatusSeverity.FATAL;
+
+  /**
+   * Returns whether the entry represents a warning or not.
+   */
+  bool get isWarning => severity == RefactoringStatusSeverity.WARNING;
+
+  @override
+  String toString() {
+    if (context != null) {
+      return "${severity}: ${message}; Context: ${context}";
+    } else {
+      return "${severity}: ${message}";
+    }
+  }
+}
+
+
+/**
+ * Severity of [RefactoringStatus].
+ */
+class RefactoringStatusSeverity {
+  /**
+   * The severity indicating the nominal case.
+   */
+  static const OK = const RefactoringStatusSeverity('OK', 0);
+
+  /**
+   * The severity indicating a warning.
+   *
+   * Use this severity if the refactoring can be performed, but you assume that
+   * the user could not be aware of problems or confusions resulting from the
+   * execution.
+   */
+  static const WARNING = const RefactoringStatusSeverity('WARNING', 2);
+
+  /**
+   * The severity indicating an error.
+   *
+   * Use this severity if the refactoring can be performed, but the refactoring
+   * will not be behavior preserving and/or the partial execution will lead to
+   * an inconsistent state (e.g. compile errors).
+   */
+  static const ERROR = const RefactoringStatusSeverity('ERROR', 3);
+
+  /**
+   * The severity indicating a fatal error.
+   *
+   * Use this severity if the refactoring cannot be performed, and execution
+   * would lead to major problems. Note that this completely blocks the user
+   * from performing this refactoring.
+   *
+   * It is often preferable to use an [ERROR] status and allow a partial
+   * execution (e.g. if just one reference to a refactored element cannot be
+   * updated).
+   */
+  static const FATAL = const RefactoringStatusSeverity('FATAL', 4);
+
+  final String name;
+  final int ordinal;
+
+  const RefactoringStatusSeverity(this.name, this.ordinal);
+
+  @override
+  String toString() => name;
+
+  /**
+   * Returns the most severe [RefactoringStatusSeverity].
+   */
+  static RefactoringStatusSeverity _max(RefactoringStatusSeverity a,
+      RefactoringStatusSeverity b) {
+    if (b.ordinal > a.ordinal) {
+      return b;
+    }
+    return a;
+  }
+}