Fixes #776: Add settings for the kind of newline to use

gson/src/main/java/com/google/gson/FormattingStyle.java

@@ -0,0 +1,98 @@
+/*
+ * Copyright (C) 2022 Google Inc.
+ *
+ * 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.gson;
+
+import java.util.Objects;
+
+/**
+ * A class used to control what the serialization looks like.
+ *
+ * <p>It currently defines the kind of newline to use, and the indent, but
+ * might add more in the future.</p>
+ *
+ * @see <a href="https://en.wikipedia.org/wiki/Newline">Wikipedia Newline article</a>
+ *
+ * @since $next-version$
+ */
+public class FormattingStyle {
+  private final String newline;
+  private final String indent;
+
+  static public final FormattingStyle DEFAULT =
+      new FormattingStyle("\n", "  ");
+
+  private FormattingStyle(String newline, String indent) {
+    Objects.requireNonNull(newline, "newline == null");
+    Objects.requireNonNull(indent, "indent == null");
+    if (!newline.matches("[\r\n]*")) {
+      throw new IllegalArgumentException(
+          "Only combinations of \\n and \\r are allowed in newline.");
+    }
+    if (!indent.matches("[ \t]*")) {
+      throw new IllegalArgumentException(
+          "Only combinations of spaces and tabs allowed in indent.");
+    }
+    this.newline = newline;
+    this.indent = indent;
+  }
+
+  /**
+   * Creates a {@link FormattingStyle} with the specified newline setting.
+   *
+   * <p>It can be used to accommodate certain OS convention, for example
+   * hardcode {@code "\r"} for Linux and macos, {@code "\r\n"} for Windows, or
+   * call {@link java.lang.System#lineSeparator()} to match the current OS.</p>
+   *
+   * <p>Only combinations of {@code \n} and {@code \r} are allowed.</p>
+   *
+   * @param newline the string value that will be used as newline.
+   * @return a newly created {@link FormattingStyle}
+   */
+  public FormattingStyle withNewline(String newline) {
+    return new FormattingStyle(newline, this.indent);
+  }
+
+  /**
+   * Creates a {@link FormattingStyle} with the specified indent string.
+   *
+   * <p>Only combinations of spaces and tabs allowed in indent.</p>
+   *
+   * @param indent the string value that will be used as indent.
+   * @return a newly created {@link FormattingStyle}
+   */
+  public FormattingStyle withIndent(String indent) {
+    return new FormattingStyle(this.newline, indent);
+  }
+
+  /**
+   * The string value that will be used as a newline.
+   *
+   * @return the newline value.
+   */
+  public String getNewline() {
+    return this.newline;
+  }
+
+  /**
+   * The string value that will be used as indent.
+   *
+   * @return the indent value.
+   */
+  public String getIndent() {
+    return this.indent;
+  }
+}

gson/src/main/java/com/google/gson/Gson.java

@@ -69,8 +69,8 @@
  *
  * <p>You can create a Gson instance by invoking {@code new Gson()} if the default configuration
  * is all you need. You can also use {@link GsonBuilder} to build a Gson instance with various
- * configuration options such as versioning support, pretty printing, custom
- * {@link JsonSerializer}s, {@link JsonDeserializer}s, and {@link InstanceCreator}s.</p>
+ * configuration options such as versioning support, pretty printing, custom newline, custom indent,
+ * custom {@link JsonSerializer}s, {@link JsonDeserializer}s, and {@link InstanceCreator}s.</p>
  *
  * <p>Here is an example of how Gson is used for a simple Class:
  *
@@ -141,7 +141,7 @@
 public final class Gson {
   static final boolean DEFAULT_JSON_NON_EXECUTABLE = false;
   static final boolean DEFAULT_LENIENT = false;
-  static final boolean DEFAULT_PRETTY_PRINT = false;
+  static final FormattingStyle DEFAULT_FORMATTING_STYLE = null;
   static final boolean DEFAULT_ESCAPE_HTML = true;
   static final boolean DEFAULT_SERIALIZE_NULLS = false;
   static final boolean DEFAULT_COMPLEX_MAP_KEYS = false;
@@ -182,7 +182,7 @@ public final class Gson {
   final boolean complexMapKeySerialization;
   final boolean generateNonExecutableJson;
   final boolean htmlSafe;
-  final boolean prettyPrinting;
+  final FormattingStyle formattingStyle;
   final boolean lenient;
   final boolean serializeSpecialFloatingPointValues;
   final boolean useJdkUnsafe;
@@ -202,7 +202,9 @@ public final class Gson {
    * <ul>
    *   <li>The JSON generated by <code>toJson</code> methods is in compact representation. This
    *   means that all the unneeded white-space is removed. You can change this behavior with
-   *   {@link GsonBuilder#setPrettyPrinting()}. </li>
+   *   {@link GsonBuilder#setPrettyPrinting()}.</li>
+   *   <li>When the JSON generated contains more than one line, the kind of newline and indent to
+   *   use can be configured with {@link GsonBuilder#setPrettyPrinting(FormattingStyle)}.</li>
    *   <li>The generated JSON omits all the fields that are null. Note that nulls in arrays are
    *   kept as is since an array is an ordered list. Moreover, if a field is not null, but its
    *   generated JSON is empty, the field is kept. You can configure Gson to serialize null values
@@ -234,7 +236,7 @@ public Gson() {
     this(Excluder.DEFAULT, DEFAULT_FIELD_NAMING_STRATEGY,
         Collections.<Type, InstanceCreator<?>>emptyMap(), DEFAULT_SERIALIZE_NULLS,
         DEFAULT_COMPLEX_MAP_KEYS, DEFAULT_JSON_NON_EXECUTABLE, DEFAULT_ESCAPE_HTML,
-        DEFAULT_PRETTY_PRINT, DEFAULT_LENIENT, DEFAULT_SPECIALIZE_FLOAT_VALUES,
+        DEFAULT_FORMATTING_STYLE, DEFAULT_LENIENT, DEFAULT_SPECIALIZE_FLOAT_VALUES,
         DEFAULT_USE_JDK_UNSAFE,
         LongSerializationPolicy.DEFAULT, DEFAULT_DATE_PATTERN, DateFormat.DEFAULT, DateFormat.DEFAULT,
         Collections.<TypeAdapterFactory>emptyList(), Collections.<TypeAdapterFactory>emptyList(),
@@ -245,7 +247,7 @@ public Gson() {
   Gson(Excluder excluder, FieldNamingStrategy fieldNamingStrategy,
       Map<Type, InstanceCreator<?>> instanceCreators, boolean serializeNulls,
       boolean complexMapKeySerialization, boolean generateNonExecutableGson, boolean htmlSafe,
-      boolean prettyPrinting, boolean lenient, boolean serializeSpecialFloatingPointValues,
+      FormattingStyle formattingStyle, boolean lenient, boolean serializeSpecialFloatingPointValues,
       boolean useJdkUnsafe,
       LongSerializationPolicy longSerializationPolicy, String datePattern, int dateStyle,
       int timeStyle, List<TypeAdapterFactory> builderFactories,
@@ -261,7 +263,7 @@ public Gson() {
     this.complexMapKeySerialization = complexMapKeySerialization;
     this.generateNonExecutableJson = generateNonExecutableGson;
     this.htmlSafe = htmlSafe;
-    this.prettyPrinting = prettyPrinting;
+    this.formattingStyle = formattingStyle;
     this.lenient = lenient;
     this.serializeSpecialFloatingPointValues = serializeSpecialFloatingPointValues;
     this.useJdkUnsafe = useJdkUnsafe;
@@ -702,7 +704,7 @@ public JsonElement toJsonTree(Object src) {
    * <pre>
    * Type typeOfSrc = new TypeToken&lt;Collection&lt;Foo&gt;&gt;(){}.getType();
    * </pre>
-   * @return Json representation of {@code src}
+   * @return JSON representation of {@code src}.
    * @since 1.4
    *
    * @see #toJsonTree(Object)
@@ -724,7 +726,7 @@ public JsonElement toJsonTree(Object src, Type typeOfSrc) {
    * {@link Writer}, use {@link #toJson(Object, Appendable)} instead.
    *
    * @param src the object for which JSON representation is to be created
-   * @return Json representation of {@code src}.
+   * @return JSON representation of {@code src}.
    *
    * @see #toJson(Object, Appendable)
    * @see #toJson(Object, Type)
@@ -749,7 +751,7 @@ public String toJson(Object src) {
    * <pre>
    * Type typeOfSrc = new TypeToken&lt;Collection&lt;Foo&gt;&gt;(){}.getType();
    * </pre>
-   * @return JSON representation of {@code src}
+   * @return JSON representation of {@code src}.
    *
    * @see #toJson(Object, Type, Appendable)
    * @see #toJson(Object)
@@ -855,7 +857,7 @@ public void toJson(Object src, Type typeOfSrc, JsonWriter writer) throws JsonIOE
    * Converts a tree of {@link JsonElement}s into its equivalent JSON representation.
    *
    * @param jsonElement root of a tree of {@link JsonElement}s
-   * @return JSON String representation of the tree
+   * @return JSON String representation of the tree.
    * @since 1.4
    */
   public String toJson(JsonElement jsonElement) {
@@ -891,16 +893,15 @@ public void toJson(JsonElement jsonElement, Appendable writer) throws JsonIOExce
    *   <li>{@link GsonBuilder#serializeNulls()}</li>
    *   <li>{@link GsonBuilder#setLenient()}</li>
    *   <li>{@link GsonBuilder#setPrettyPrinting()}</li>
+   *   <li>{@link GsonBuilder#setPrettyPrinting(FormattingStyle)}</li>
    * </ul>
    */
   public JsonWriter newJsonWriter(Writer writer) throws IOException {
     if (generateNonExecutableJson) {
       writer.write(JSON_NON_EXECUTABLE_PREFIX);
     }
     JsonWriter jsonWriter = new JsonWriter(writer);
-    if (prettyPrinting) {
-      jsonWriter.setIndent("  ");
-    }
+    jsonWriter.setFormattingStyle(formattingStyle);
     jsonWriter.setHtmlSafe(htmlSafe);
     jsonWriter.setLenient(lenient);
     jsonWriter.setSerializeNulls(serializeNulls);

gson/src/main/java/com/google/gson/GsonBuilder.java

@@ -23,7 +23,7 @@
 import static com.google.gson.Gson.DEFAULT_LENIENT;
 import static com.google.gson.Gson.DEFAULT_NUMBER_TO_NUMBER_STRATEGY;
 import static com.google.gson.Gson.DEFAULT_OBJECT_TO_NUMBER_STRATEGY;
-import static com.google.gson.Gson.DEFAULT_PRETTY_PRINT;
+import static com.google.gson.Gson.DEFAULT_FORMATTING_STYLE;
 import static com.google.gson.Gson.DEFAULT_SERIALIZE_NULLS;
 import static com.google.gson.Gson.DEFAULT_SPECIALIZE_FLOAT_VALUES;
 import static com.google.gson.Gson.DEFAULT_USE_JDK_UNSAFE;
@@ -98,7 +98,7 @@ public final class GsonBuilder {
   private boolean complexMapKeySerialization = DEFAULT_COMPLEX_MAP_KEYS;
   private boolean serializeSpecialFloatingPointValues = DEFAULT_SPECIALIZE_FLOAT_VALUES;
   private boolean escapeHtmlChars = DEFAULT_ESCAPE_HTML;
-  private boolean prettyPrinting = DEFAULT_PRETTY_PRINT;
+  private FormattingStyle formattingStyle = DEFAULT_FORMATTING_STYLE;
   private boolean generateNonExecutableJson = DEFAULT_JSON_NON_EXECUTABLE;
   private boolean lenient = DEFAULT_LENIENT;
   private boolean useJdkUnsafe = DEFAULT_USE_JDK_UNSAFE;
@@ -129,7 +129,7 @@ public GsonBuilder() {
     this.complexMapKeySerialization = gson.complexMapKeySerialization;
     this.generateNonExecutableJson = gson.generateNonExecutableJson;
     this.escapeHtmlChars = gson.htmlSafe;
-    this.prettyPrinting = gson.prettyPrinting;
+    this.formattingStyle = gson.formattingStyle;
     this.lenient = gson.lenient;
     this.serializeSpecialFloatingPointValues = gson.serializeSpecialFloatingPointValues;
     this.longSerializationPolicy = gson.longSerializationPolicy;
@@ -478,13 +478,26 @@ public GsonBuilder addDeserializationExclusionStrategy(ExclusionStrategy strateg
   }
 
   /**
-   * Configures Gson to output Json that fits in a page for pretty printing. This option only
-   * affects Json serialization.
+   * Configures Gson to output JSON that fits in a page for pretty printing. This option only
+   * affects JSON serialization.
    *
    * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
    */
   public GsonBuilder setPrettyPrinting() {
-    prettyPrinting = true;
+    return setPrettyPrinting(FormattingStyle.DEFAULT);
+  }
+
+  /**
+   * Configures Gson to output JSON that uses a certain kind of formatting stile (for example newline and indent).
+   * This option only affects JSON serialization.
+   *
+   * <p>Has no effect if the serialized format is a single line.</p>
+   *
+   * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
+   * @since $next-version$
+   */
+  public GsonBuilder setPrettyPrinting(FormattingStyle formattingStyle) {
+    this.formattingStyle = formattingStyle;
     return this;
   }
 
@@ -761,7 +774,7 @@ public Gson create() {
 
     return new Gson(excluder, fieldNamingPolicy, new HashMap<>(instanceCreators),
         serializeNulls, complexMapKeySerialization,
-        generateNonExecutableJson, escapeHtmlChars, prettyPrinting, lenient,
+        generateNonExecutableJson, escapeHtmlChars, formattingStyle, lenient,
         serializeSpecialFloatingPointValues, useJdkUnsafe, longSerializationPolicy,
         datePattern, dateStyle, timeStyle, new ArrayList<>(this.factories),
         new ArrayList<>(this.hierarchyFactories), factories,

gson/src/main/java/com/google/gson/JsonPrimitive.java

@@ -106,7 +106,7 @@ public boolean getAsBoolean() {
     if (isBoolean()) {
       return (Boolean) value;
     }
-	// Check to see if the value as a String is "true" in any case.
+    // Check to see if the value as a String is "true" in any case.
     return Boolean.parseBoolean(getAsString());
   }
 

gson/src/main/java/com/google/gson/stream/JsonWriter.java

@@ -36,6 +36,8 @@
 import java.util.concurrent.atomic.AtomicLong;
 import java.util.regex.Pattern;
 
+import com.google.gson.FormattingStyle;
+
 /**
  * Writes a JSON (<a href="http://www.ietf.org/rfc/rfc7159.txt">RFC 7159</a>)
  * encoded value to a stream, one token at a time. The stream includes both
@@ -180,10 +182,9 @@ public class JsonWriter implements Closeable, Flushable {
   }
 
   /**
-   * A string containing a full set of spaces for a single level of
-   * indentation, or null for no pretty printing.
+   * The settings used for pretty printing, or null for no pretty printing.
    */
-  private String indent;
+  private FormattingStyle formattingStyle;
 
   /**
    * The name/value separator; either ":" or ": ".
@@ -217,14 +218,44 @@ public JsonWriter(Writer out) {
    */
   public final void setIndent(String indent) {
     if (indent.length() == 0) {
-      this.indent = null;
+      setFormattingStyle(null);
+    } else {
+      setFormattingStyle(FormattingStyle.DEFAULT.withIndent(indent));
+    }
+  }
+
+  /**
+   * Sets the pretty printing style to be used in the encoded document.
+   * No pretty printing if null.
+   *
+   * <p>Sets the various attributes to be used in the encoded document. 
+   * For example the indentation string to be repeated for each level of indentation.
+   * Or the newline style, to accommodate various OS styles.</p>
+   *
+   * <p>Has no effect if the serialized format is a single line.</p>
+   *
+   * @param formattingStyle the style used for pretty printing, no pretty printing if null.
+   * @since $next-version$
+   */
+  public final void setFormattingStyle(FormattingStyle formattingStyle) {
+    this.formattingStyle = formattingStyle;
+    if (formattingStyle == null) {
       this.separator = ":";
     } else {
-      this.indent = indent;
       this.separator = ": ";
     }
   }
 
+  /**
+   * Returns the pretty printing style used by this writer.
+   *
+   * @return the FormattingStyle that will be used.
+   * @since $next-version$
+   */
+  public final FormattingStyle getFormattingStyle() {
+    return formattingStyle;
+  }
+
   /**
    * Configure this writer to relax its syntax rules. By default, this writer
    * only emits well-formed JSON as specified by <a
@@ -645,13 +676,13 @@ private void string(String value) throws IOException {
   }
 
   private void newline() throws IOException {
-    if (indent == null) {
+    if (formattingStyle == null) {
       return;
     }
 
-    out.write('\n');
+    out.write(formattingStyle.getNewline());
     for (int i = 1, size = stackSize; i < size; i++) {
-      out.write(indent);
+      out.write(formattingStyle.getIndent());
     }
   }