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';
+
+
+/**
+ * Creates a new [RefactoringStatus] with [RefactoringStatusSeverity.ERROR].
+ */
+RefactoringStatus createErrorStatus(String msg,

[Brian Wilkerson, 2014/08/11 16:27:47]

I would have made these named constructors:

  RefactoringStatus.error(String message, [RefactoringContext context])

It would be shorter to type, make it easier to keep these methods with the
class, and wouldn't add to the top-level name space.

[scheglov, 2014/08/11 18:06:24]

Thank you!
Done.

+    [RefactoringStatusContext context]) {
+  RefactoringStatus status = new RefactoringStatus();
+  status.addError(msg, context);
+  return status;
+}
+
+
+/**
+ * Creates a new [RefactoringStatus] with [RefactoringStatusSeverity.FATAL].
+ */
+RefactoringStatus createFatalErrorStatus(String msg,
+    [RefactoringStatusContext context]) {
+  RefactoringStatus status = new RefactoringStatus();
+  status.addFatalError(msg, context);
+  return status;
+}
+
+
+/**
+ * Creates a new [RefactoringStatus] with [RefactoringStatusSeverity.WARNING].
+ */
+RefactoringStatus createWarningStatus(String msg,
+    [RefactoringStatusContext context]) {
+  RefactoringStatus status = new RefactoringStatus();
+  status.addWarning(msg, context);
+  return status;
+}
+
+
+/**
+ * An outcome of a condition checking operation.
+ */
+class RefactoringStatus {
+  RefactoringStatusSeverity _severity = RefactoringStatusSeverity.OK;

[Brian Wilkerson, 2014/08/11 16:27:46]

Please document this field.

[scheglov, 2014/08/11 18:06:24]

Done.

+
+  /**
+   * A list of [RefactoringStatusEntry]s.
+   */
+  final List<RefactoringStatusEntry> entries = [];
+
+  /**
+   * Returns the [RefactoringStatusEntry] with the highest severity, or `null`
+   * if no entries.
+   */
+  RefactoringStatusEntry get entryWithHighestSeverity {
+    if (entries.isEmpty) {
+      return null;
+    }
+    RefactoringStatusEntry result = entries[0];
+    for (RefactoringStatusEntry entry in entries) {
+      if (result.severity.ordinal < entry.severity.ordinal) {

[Brian Wilkerson, 2014/08/11 16:27:47]

Given that _severity is the maximum severity, couldn't we return as soon as we
find the first entry with that severity?

[scheglov, 2014/08/11 18:06:24]

Done.

+        result = entry;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * 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));
+  }
+
+  /**
+   * 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) {
+      RefactoringStatusSeverity severity = entry.severity;
+      if (severity == RefactoringStatusSeverity.ERROR) {
+        severity = RefactoringStatusSeverity.FATAL;
+      }
+      result._addEntry(
+          new RefactoringStatusEntry(severity, entry.message, entry.context));

[Brian Wilkerson, 2014/08/11 16:27:47]

Could we share entries when the severity has not changed? It might not be worth
it, but it looks like entries are immutable.

[scheglov, 2014/08/11 18:06:24]

Done.

+    }
+    return result;
+  }
+
+  /**
+   * Merges the receiver and the parameter statuses.
+   *
+   * The resulting list of entries in the receiver will contain entries from
+   * both.
+   *
+   * The resulting severity in the receiver will be the more severe of its
+   * current severityand the parameter's severity.

[Brian Wilkerson, 2014/08/11 16:27:46]

"severityand" --> "severity and"

[scheglov, 2014/08/11 18:06:24]

Done.

+   *
+   * Merging with `null` is allowed - it has no effect.
+   */
+  void merge(RefactoringStatus other) {

[Brian Wilkerson, 2014/08/11 16:27:47]

When I saw this method being used I had to come back and check the semantics. My
expectation from the name at the call site was that the method would return a
new "merged" result but wouldn't modify the original (and I was about to comment
that you forgot to capture the result). Turns out it's the name that's
confusing. How about "addFromStatus" or "addAll" or "addEntries"?

[scheglov, 2014/08/11 18:06:25]

Done.

+    if (other == null) {
+      return;
+    }
+    entries.addAll(other.entries);
+    _severity = _max(_severity, other.severity);
+  }
+
+  @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 = _max(_severity, entry.severity);
+  }
+
+  /**
+   * Returns the [RefactoringStatusSeverity] with the maximal ordinal.
+   */
+  static RefactoringStatusSeverity _max(RefactoringStatusSeverity a,

[Brian Wilkerson, 2014/08/11 16:27:46]

This should be defined on RefactoringStatusSeverity.

[scheglov, 2014/08/11 18:06:24]

Done.

+      RefactoringStatusSeverity b) {
+    if (b.ordinal > a.ordinal) {
+      return b;
+    }
+    return a;
+  }
+}
+
+
+/**
+ * [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 {

[Brian Wilkerson, 2014/08/11 16:27:47]

Should this be a subclass of Enum?

[scheglov, 2014/08/11 18:06:24]

I try to avoid using Java artefacts.

+  static const OK = const RefactoringStatusSeverity('OK', 0);
+  static const WARNING = const RefactoringStatusSeverity('WARNING', 2);
+  static const ERROR = const RefactoringStatusSeverity('ERROR', 3);
+  static const FATAL = const RefactoringStatusSeverity('FATAL', 4);

[Brian Wilkerson, 2014/08/11 16:27:47]

It would be good to document these severities, especially the difference between
FATAL and ERROR.

[scheglov, 2014/08/11 18:06:24]

Done.

+
+  final String name;
+  final int ordinal;
+
+  const RefactoringStatusSeverity(this.name, this.ordinal);
+
+  @override
+  String toString() => name;
+}