Initial work on refactorings.

pkg/analysis_services/lib/refactoring/refactoring.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.
+
+library services.refactoring;
+
+import 'package:analysis_services/correction/change.dart';
+import 'package:analysis_services/correction/status.dart';
+import 'package:analysis_services/refactoring/progress_monitor.dart';
+import 'package:analysis_services/search/search_engine.dart';
+import 'package:analysis_services/src/refactoring/rename_local.dart';
+import 'package:analyzer/src/generated/element.dart';
+
+
+/**
+ * Returns a [RenameRefactoring] instance for renaming [element], may be `null`
+ * if there is no support for renaming [Element]s of the given type.
+ */
+RenameRefactoring createRenameRefactoring(SearchEngine searchEngine,

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

I don't see the value in a top-level function that takes the same arguments as
the constructor.

If you just want to insulate clients from invoking the constructor directly,
then a factory constructor on Refactoring would be more appropriate.

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

Done.
However actually I missed some code.
This function is a factory, right, it should check the "element" type and return
an appropriate RenameRefactoring subtype.
Or null.
I don't know for sure if it is OK in Dart style to return null from a factory
constructor.

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

I generally wouldn't, but in this case (given that it's well documented) I'm OK
with it. The other option would be to implement an InvalidRenameRefactoring that
returns a FATAL error for everything indicating that we don't know how to rename
an element of that type. Your call.

+    Element element) {
+  return new RenameLocalRefactoringImpl(searchEngine, element);
+}
+
+/**
+ * Abstract interface for all refactorings.
+ */
+abstract class Refactoring {
+  /**
+   * Returns the human readable name of this [Refactoring].
+   */
+  String get refactoringName;
+
+  /**
+   * Checks all conditions - [checkInitialConditions] and
+   * [checkFinalConditions] to decide if refactoring can be performed.
+   */
+  RefactoringStatus checkAllConditions(ProgressMonitor pm);
+
+  /**
+   * Validates environment to check if this refactoring can be performed.
+   *
+   * This check may be slow, because many refactorings use search engine.
+   */
+  RefactoringStatus checkFinalConditions(ProgressMonitor pm);
+
+  /**
+   * Validates arguments to check if this refactoring can be performed.
+   *
+   * This check should be quick because it is used often as arguments change.
+   */
+  RefactoringStatus checkInitialConditions(ProgressMonitor pm);
+
+  /**
+   * Returns the [Change] to apply to perform this refactoring.
+   */
+  Change createChange(ProgressMonitor pm);
+
+  /**
+   * Returs `true` if the [Change] created by refactoring may be unsafe,
+   * so we want user to review the [Change] to ensure that he understands it.
+   */
+  bool requiresPreview();
+}
+
+
+/**
+ * Abstract [Refactoring] for renaming some [Element].
+ */
+abstract class RenameRefactoring implements Refactoring {
+  /**
+   * Returns the current name of the [Element].
+   */
+  String get currentName;
+
+  /**
+   * Sets the new name for the [Element].
+   */
+  void set newName(String newName);
+
+  /**
+   * Validates [newName].

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

The more information in comments the better. Perhaps something like

Validates that the [newName] is a valid identifier and does not conflict with
any existing names in any of the scopes containing the current name.

(or whatever is appropriate). Also, do we need to pass in the new name, or is it
(or can it be) expected to have been set by newName?

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

Done.

+   */
+  RefactoringStatus checkNewName(String newName);
+}