Add utilities for creating SourceChanges

pkg/analysis_server/lib/utilities/change_builder_core.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.utilities.change_builder_core;
+
+import 'package:analysis_server/src/utilities/change_builder_core.dart';
+import 'package:analysis_server/src/protocol.dart';
+import 'package:analyzer/src/generated/source.dart';
+
+/**
+ * A builder used to build a [SourceChange].
+ *
+ * Clients are not expected to subtype this class.
+ */
+abstract class ChangeBuilder {
+  /**
+   * Initialize a newly created change builder.
+   */
+  factory ChangeBuilder() = ChangeBuilderImpl;
+
+  /**
+   * Return the source change that was built.
+   */
+  SourceChange get sourceChange;
+
+  /**
+   * Use the [buildFileEdit] function to create a collection of edits to the
+   * given [source]. The edits will be added to the source change that is being
+   * built. The [timeStamp] is the time at which the [source] was last modified
+   * and is used by clients to ensure that it is safe to apply the edits.
+   */
+  void addFileEdit(Source source, int timeStamp,
+      void buildFileEdit(FileEditBuilder builder));
+}
+
+/**
+ * A builder used to build a [SourceEdit] as part of a [SourceFileEdit].
+ *
+ * Clients are not expected to subtype this class.
+ */
+abstract class EditBuilder {
+  /**
+   * Add a region of text that is part of the linked edit group with the given
+   * [groupName]. The [buildLinkedEdit] function is used to write the content of
+   * the region of text and to add suggestions for other possible values for
+   * that region.
+   */
+  void addLinkedEdit(
+      String groupName, void buildLinkedEdit(LinkedEditBuilder builder));
+
+  /**
+   * Add the given [string] to the content of the current edit.
+   */
+  void write(String string);
+
+  /**
+   * Add the given [string] to the content of the current edit and then add an
+   * end-of-line marker.
+   */
+  void writeln([String string]);
+}
+
+/**
+ * A builder used to build a [SourceFileEdit] within a [SourceChange].
+ *
+ * Clients are not expected to subtype this class.
+ */
+abstract class FileEditBuilder {
+  /**
+   * Add an insertion of text at the given [offset]. The [buildEdit] function is
+   * used to write the text to be inserted. This is fully equivalent to
+   *
+   *     addReplacement(offset, 0, buildEdit);
+   */
+  void addInsertion(int offset, void buildEdit(EditBuilder builder));
+
+  /**
+   * Add the region of text starting at the given [offset] and continuing for

[Paul Berry, 2015/04/27 16:30:10]

Since this class is used to build up a change to a file, we need to clarify
whether the offset and length are relative to the original state of the
document, the state of the document as changed so far, or the state of the
document as it will appear once all the edits have been applied.  (I suspect
it's relative to the state of the document as it will appear once all the edits
have been applied, but I haven't worked with the underlying code much so I'm not
certain).

[Brian Wilkerson, 2015/04/28 15:17:00]

Good point. I'll work on improving the docs.

+   * the given [length] to the linked edit group with the given [groupName].
+   * This is typically used to include pre-existing regions of text in a group.
+   */
+  void addLinkedPosition(int offset, int length, String groupName);
+
+  /**
+   * Add a replacement of text starting at the given [offset] and continuing for

[Paul Berry, 2015/04/27 16:30:10]

Similarly, it's not clear here whether the offset and length are relative to the
original state of the document or the state of the document as modified so far. 
(I suspect it's relative to the original state of the document).

Perhaps an example would be helpful.

[Brian Wilkerson, 2015/04/28 15:17:00]

Ditto

+   * the given [length]. The [buildEdit] function is used to write the text that
+   * will replace the specified region.
+   */
+  void addReplacement(
+      int offset, int length, void buildEdit(EditBuilder builder));
+}
+
+/**
+ * A builder used to build a [LinkedEdit] region within an edit.
+ *
+ * Clients are not expected to subtype this class.
+ */
+abstract class LinkedEditBuilder {
+  /**
+   * Add the given [value] as a suggestion with the given [kind].
+   */
+  void addSuggestion(LinkedEditSuggestionKind kind, String value);
+
+  /**
+   * Add each of the given [values] as a suggestion with the given [kind].
+   */
+  void addSuggestions(LinkedEditSuggestionKind kind, List<String> values);

[Paul Berry, 2015/04/27 16:30:10]

s/List/Iterable/ so that the caller doesn't have to make unnecessary calls to
".toList()".

[Brian Wilkerson, 2015/04/28 15:17:00]

Done

+
+  /**
+   * Add the given [string] to the content of the current edit.
+   */
+  void write(String string);
+
+  /**
+   * Add the given [string] to the content of the current edit and then add an
+   * end-of-line marker.
+   */
+  void writeln([String string]);
+}