Refactor Printer

It's now easier to customize Printer if in different situations objects should
be printed differently. Also its API is cleaner now. Names of methods of SkylarkValue objects now reflect names of Skylark functions: SkylarkValue#repr and SkylarkPrintableValue#str.

PiperOrigin-RevId: 160635154

3 files changed, 89 insertions, 8 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkPrintableValue.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkPrintableValue.java
index 24353cebe6..69426ea6c8 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkPrintableValue.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkPrintableValue.java
@@ -14,14 +14,13 @@
 package com.google.devtools.build.lib.skylarkinterface;
 
 /**
- * A Skylark value that is represented by {@code print()} differently than by {@code write()}.
+ * A Skylark value that is represented by {@code str()} differently than by {@code repr()}.
  */
 public interface SkylarkPrintableValue extends SkylarkValue {
   /**
    * Print an informal, human-readable representation of the value.
    *
-   * @param buffer the buffer to append the representation to
-   * @param quotationMark The quote style (" or ') to be used
+   * @param printer a printer to be used for formatting nested values.
    */
-  void print(Appendable buffer, char quotationMark);
+  void str(SkylarkPrinter printer);
 }
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkPrinter.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkPrinter.java
new file mode 100644
index 0000000000..0e950e4c62
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkPrinter.java
@@ -0,0 +1,83 @@
+// Copyright 2017 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.devtools.build.lib.skylarkinterface;
+
+import java.util.List;
+import javax.annotation.Nullable;
+
+/**
+ * An interface for Printer.BasePrinter
+ *
+ * <p>Allows passing Printer.BasePrinter instances to classes that can't import Printer directly
+ * because of circular dependencies.
+ */
+public interface SkylarkPrinter {
+  /** Append a char to the printer's buffer */
+  SkylarkPrinter append(char c);
+
+  /** Append a char sequence to the printer's buffer */
+  SkylarkPrinter append(CharSequence s);
+
+  /**
+   * Prints a list to the printer's buffer. All list items are rendered with {@code repr}.
+   *
+   * @param list the list
+   * @param isTuple if true, uses parentheses, otherwise, uses square brackets. Also one-element
+   *     tuples are rendered with a comma after the element.
+   * @return SkylarkPrinter
+   */
+  SkylarkPrinter printList(Iterable<?> list, boolean isTuple);
+
+  /**
+   * Prints a list to the printer's buffer. All list items are rendered with {@code repr}.
+   *
+   * @param list the list of objects to repr (each as with repr)
+   * @param before a string to print before the list items, e.g. an opening bracket
+   * @param separator a separator to print between items
+   * @param after a string to print after the list items, e.g. a closing bracket
+   * @param singletonTerminator null or a string to print after the list if it is a singleton.
+   *     The singleton case is notably relied upon in python syntax to distinguish a tuple of size
+   *     one such as ("foo",) from a merely parenthesized object such as ("foo")
+   * @return SkylarkPrinter
+   */
+  SkylarkPrinter printList(
+      Iterable<?> list, String before, String separator, String after,
+      @Nullable String singletonTerminator);
+
+  /**
+   * Renders an object with {@code repr} and append to the printer's buffer.
+   */
+  SkylarkPrinter repr(Object o);
+
+  /**
+   * Performs Python-style string formatting, as per {@code pattern % tuple}.
+   * Limitations: only {@code %d %s %r %%} are supported.
+   *
+   * @param pattern a format string
+   * @param arguments an array containing positional arguments
+   * @return SkylarkPrinter
+   */
+  SkylarkPrinter format(String pattern, Object... arguments);
+
+  /**
+   * Performs Python-style string formatting, as per {@code pattern % tuple}.
+   * Limitations: only {@code %d %s %r %%} are supported.
+   *
+   * @param pattern a format string
+   * @param arguments a list containing positional arguments
+   * @return SkylarkPrinter
+   */
+  SkylarkPrinter formatWithList(String pattern, List<?> arguments);
+}
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkValue.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkValue.java
index bf72821c86..a7c8c2779b 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkValue.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkValue.java
@@ -17,7 +17,7 @@ package com.google.devtools.build.lib.skylarkinterface;
 /**
  * Java objects that are also Skylark values.
  *
- * <p>This is used for extending the Skylark interpreted with domain-specific values.
+ * <p>This is used for extending the Skylark interpreter with domain-specific values.
  */
 public interface SkylarkValue {
 
@@ -34,8 +34,7 @@ public interface SkylarkValue {
    *
    * <p>For regular data structures, the value should be parsable back into an equal data structure.
    *
-   * @param buffer the buffer to append the representation to
-   * @param quotationMark The quote style (" or ') to be used
+   * @param printer a printer to be used for formatting nested values.
    */
-  void write(Appendable buffer, char quotationMark);
+  void repr(SkylarkPrinter printer);
 }