FormattingStyle follow-up (#2327)

* FormattingStyle follow-up

* Add links to FormattingStyle

* Use Truth for FormattingStyleTest

* Reduce pull request scope to Javadoc and minor code changes
This commit is contained in:
Marcono1234 2023-03-19 17:15:35 +01:00 committed by GitHub
parent 6eddbf3031
commit 26229d33d8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 38 additions and 21 deletions

View File

@ -16,14 +16,17 @@
package com.google.gson; package com.google.gson;
import com.google.gson.stream.JsonWriter;
import java.util.Objects; import java.util.Objects;
/** /**
* A class used to control what the serialization looks like. * A class used to control what the serialization output looks like.
* *
* <p>It currently defines the kind of newline to use, and the indent, but * <p>It currently defines the kind of newline to use, and the indent, but
* might add more in the future.</p> * might add more in the future.</p>
* *
* @see GsonBuilder#setPrettyPrinting(FormattingStyle)
* @see JsonWriter#setFormattingStyle(FormattingStyle)
* @see <a href="https://en.wikipedia.org/wiki/Newline">Wikipedia Newline article</a> * @see <a href="https://en.wikipedia.org/wiki/Newline">Wikipedia Newline article</a>
* *
* @since $next-version$ * @since $next-version$
@ -32,7 +35,11 @@ public class FormattingStyle {
private final String newline; private final String newline;
private final String indent; private final String indent;
static public final FormattingStyle DEFAULT = /**
* The default pretty printing formatting style using {@code "\n"} as
* newline and two spaces as indent.
*/
public static final FormattingStyle DEFAULT =
new FormattingStyle("\n", " "); new FormattingStyle("\n", " ");
private FormattingStyle(String newline, String indent) { private FormattingStyle(String newline, String indent) {
@ -44,7 +51,7 @@ public class FormattingStyle {
} }
if (!indent.matches("[ \t]*")) { if (!indent.matches("[ \t]*")) {
throw new IllegalArgumentException( throw new IllegalArgumentException(
"Only combinations of spaces and tabs allowed in indent."); "Only combinations of spaces and tabs are allowed in indent.");
} }
this.newline = newline; this.newline = newline;
this.indent = indent; this.indent = indent;
@ -54,7 +61,7 @@ public class FormattingStyle {
* Creates a {@link FormattingStyle} with the specified newline setting. * Creates a {@link FormattingStyle} with the specified newline setting.
* *
* <p>It can be used to accommodate certain OS convention, for example * <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 * hardcode {@code "\n"} for Linux and macOS, {@code "\r\n"} for Windows, or
* call {@link java.lang.System#lineSeparator()} to match the current OS.</p> * call {@link java.lang.System#lineSeparator()} to match the current OS.</p>
* *
* <p>Only combinations of {@code \n} and {@code \r} are allowed.</p> * <p>Only combinations of {@code \n} and {@code \r} are allowed.</p>

View File

@ -481,6 +481,9 @@ public final class GsonBuilder {
* Configures Gson to output JSON that fits in a page for pretty printing. This option only * Configures Gson to output JSON that fits in a page for pretty printing. This option only
* affects JSON serialization. * affects JSON serialization.
* *
* <p>This is a convenience method which simply calls {@link #setPrettyPrinting(FormattingStyle)}
* with {@link FormattingStyle#DEFAULT}.
*
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
*/ */
public GsonBuilder setPrettyPrinting() { public GsonBuilder setPrettyPrinting() {
@ -488,11 +491,12 @@ public final class GsonBuilder {
} }
/** /**
* Configures Gson to output JSON that uses a certain kind of formatting stile (for example newline and indent). * Configures Gson to output JSON that uses a certain kind of formatting style (for example newline and indent).
* This option only affects JSON serialization. * This option only affects JSON serialization. By default Gson produces compact JSON output without any formatting.
* *
* <p>Has no effect if the serialized format is a single line.</p> * <p>Has no effect if the serialized format is a single line.</p>
* *
* @param formattingStyle the formatting style to use.
* @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern * @return a reference to this {@code GsonBuilder} object to fulfill the "Builder" pattern
* @since $next-version$ * @since $next-version$
*/ */

View File

@ -217,7 +217,7 @@ public class JsonWriter implements Closeable, Flushable {
* @param indent a string containing only whitespace. * @param indent a string containing only whitespace.
*/ */
public final void setIndent(String indent) { public final void setIndent(String indent) {
if (indent.length() == 0) { if (indent.isEmpty()) {
setFormattingStyle(null); setFormattingStyle(null);
} else { } else {
setFormattingStyle(FormattingStyle.DEFAULT.withIndent(indent)); setFormattingStyle(FormattingStyle.DEFAULT.withIndent(indent));
@ -226,7 +226,7 @@ public class JsonWriter implements Closeable, Flushable {
/** /**
* Sets the pretty printing style to be used in the encoded document. * Sets the pretty printing style to be used in the encoded document.
* No pretty printing if null. * No pretty printing is done if the given style is {@code null}.
* *
* <p>Sets the various attributes to be used in the encoded document. * <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. * For example the indentation string to be repeated for each level of indentation.
@ -234,7 +234,7 @@ public class JsonWriter implements Closeable, Flushable {
* *
* <p>Has no effect if the serialized format is a single line.</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. * @param formattingStyle the style used for pretty printing, no pretty printing if {@code null}.
* @since $next-version$ * @since $next-version$
*/ */
public final void setFormattingStyle(FormattingStyle formattingStyle) { public final void setFormattingStyle(FormattingStyle formattingStyle) {
@ -249,7 +249,7 @@ public class JsonWriter implements Closeable, Flushable {
/** /**
* Returns the pretty printing style used by this writer. * Returns the pretty printing style used by this writer.
* *
* @return the FormattingStyle that will be used. * @return the {@code FormattingStyle} that will be used.
* @since $next-version$ * @since $next-version$
*/ */
public final FormattingStyle getFormattingStyle() { public final FormattingStyle getFormattingStyle() {

View File

@ -15,8 +15,7 @@
*/ */
package com.google.gson.functional; package com.google.gson.functional;
import static org.junit.Assert.assertArrayEquals; import static com.google.common.truth.Truth.assertThat;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.fail; import static org.junit.Assert.fail;
import com.google.gson.FormattingStyle; import com.google.gson.FormattingStyle;
@ -54,7 +53,7 @@ public class FormattingStyleTest {
Gson gson = new GsonBuilder().setPrettyPrinting().create(); Gson gson = new GsonBuilder().setPrettyPrinting().create();
String json = gson.toJson(INPUT); String json = gson.toJson(INPUT);
// Make sure the default uses LF, like before. // Make sure the default uses LF, like before.
assertEquals(EXPECTED_LF, json); assertThat(json).isEqualTo(EXPECTED_LF);
} }
@Test @Test
@ -62,7 +61,7 @@ public class FormattingStyleTest {
FormattingStyle style = FormattingStyle.DEFAULT.withNewline("\r\n"); FormattingStyle style = FormattingStyle.DEFAULT.withNewline("\r\n");
Gson gson = new GsonBuilder().setPrettyPrinting(style).create(); Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
String json = gson.toJson(INPUT); String json = gson.toJson(INPUT);
assertEquals(EXPECTED_CRLF, json); assertThat(json).isEqualTo(EXPECTED_CRLF);
} }
@Test @Test
@ -70,7 +69,7 @@ public class FormattingStyleTest {
FormattingStyle style = FormattingStyle.DEFAULT.withNewline("\n"); FormattingStyle style = FormattingStyle.DEFAULT.withNewline("\n");
Gson gson = new GsonBuilder().setPrettyPrinting(style).create(); Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
String json = gson.toJson(INPUT); String json = gson.toJson(INPUT);
assertEquals(EXPECTED_LF, json); assertThat(json).isEqualTo(EXPECTED_LF);
} }
@Test @Test
@ -78,7 +77,7 @@ public class FormattingStyleTest {
FormattingStyle style = FormattingStyle.DEFAULT.withNewline("\r"); FormattingStyle style = FormattingStyle.DEFAULT.withNewline("\r");
Gson gson = new GsonBuilder().setPrettyPrinting(style).create(); Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
String json = gson.toJson(INPUT); String json = gson.toJson(INPUT);
assertEquals(EXPECTED_CR, json); assertThat(json).isEqualTo(EXPECTED_CR);
} }
@Test @Test
@ -86,7 +85,7 @@ public class FormattingStyleTest {
FormattingStyle style = FormattingStyle.DEFAULT.withNewline(System.lineSeparator()); FormattingStyle style = FormattingStyle.DEFAULT.withNewline(System.lineSeparator());
Gson gson = new GsonBuilder().setPrettyPrinting(style).create(); Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
String json = gson.toJson(INPUT); String json = gson.toJson(INPUT);
assertEquals(EXPECTED_OS, json); assertThat(json).isEqualTo(EXPECTED_OS);
} }
@Test @Test
@ -96,7 +95,7 @@ public class FormattingStyleTest {
FormattingStyle style = FormattingStyle.DEFAULT.withNewline(newline).withIndent(indent); FormattingStyle style = FormattingStyle.DEFAULT.withNewline(newline).withIndent(indent);
Gson gson = new GsonBuilder().setPrettyPrinting(style).create(); Gson gson = new GsonBuilder().setPrettyPrinting(style).create();
String json = gson.toJson(INPUT); String json = gson.toJson(INPUT);
assertEquals(buildExpected(newline, indent), json); assertThat(json).isEqualTo(buildExpected(newline, indent));
} }
} }
} }
@ -115,11 +114,11 @@ public class FormattingStyleTest {
String toParse = buildExpected(newline, indent); String toParse = buildExpected(newline, indent);
actualParsed = gson.fromJson(toParse, INPUT.getClass()); actualParsed = gson.fromJson(toParse, INPUT.getClass());
assertArrayEquals(INPUT, actualParsed); assertThat(actualParsed).isEqualTo(INPUT);
// Parse the mixed string with the gson parsers configured with various newline / indents. // Parse the mixed string with the gson parsers configured with various newline / indents.
actualParsed = gson.fromJson(jsonStringMix, INPUT.getClass()); actualParsed = gson.fromJson(jsonStringMix, INPUT.getClass());
assertArrayEquals(INPUT, actualParsed); assertThat(actualParsed).isEqualTo(INPUT);
} }
} }
} }
@ -127,22 +126,29 @@ public class FormattingStyleTest {
@Test @Test
public void testStyleValidations() { public void testStyleValidations() {
try { try {
// TBD if we want to accept \u2028 and \u2029. For now we don't. // TBD if we want to accept \u2028 and \u2029. For now we don't because JSON specification
// does not consider them to be newlines
FormattingStyle.DEFAULT.withNewline("\u2028"); FormattingStyle.DEFAULT.withNewline("\u2028");
fail("Gson should not accept anything but \\r and \\n for newline"); fail("Gson should not accept anything but \\r and \\n for newline");
} catch (IllegalArgumentException expected) { } catch (IllegalArgumentException expected) {
assertThat(expected).hasMessageThat()
.isEqualTo("Only combinations of \\n and \\r are allowed in newline.");
} }
try { try {
FormattingStyle.DEFAULT.withNewline("NL"); FormattingStyle.DEFAULT.withNewline("NL");
fail("Gson should not accept anything but \\r and \\n for newline"); fail("Gson should not accept anything but \\r and \\n for newline");
} catch (IllegalArgumentException expected) { } catch (IllegalArgumentException expected) {
assertThat(expected).hasMessageThat()
.isEqualTo("Only combinations of \\n and \\r are allowed in newline.");
} }
try { try {
FormattingStyle.DEFAULT.withIndent("\f"); FormattingStyle.DEFAULT.withIndent("\f");
fail("Gson should not accept anything but space and tab for indent"); fail("Gson should not accept anything but space and tab for indent");
} catch (IllegalArgumentException expected) { } catch (IllegalArgumentException expected) {
assertThat(expected).hasMessageThat()
.isEqualTo("Only combinations of spaces and tabs are allowed in indent.");
} }
} }