JSON formatting using Gson

[abelk2]

This PR adds support for JSON formatting using Google's Gson library.
Motivation:

• In case of some files (e.g. i18n related ones) alphabetically sorting JSON by keys would be very useful. However, the already existing formatter (called simple, based on org.json) would make this hard to implement, as its internal representation for key-value pairs does not guarantee any order. See the following examples which demonstrate that simple does some kind of key ordering, but not alphabetical:
  • objectWithNullBefore.json -> objectWithNullAfter.json (reordered, looks alphabetically sorted)
  • cucumberJsonSampleBefore.json -> cucumberJsonSampleAfter.json (reordered as well, but not in alphabetical order)
• Gson guarantees the same order in its internal representation as in the originally parsed file. Writing that representation back into a file will produce the same order. This way the user can freely choose between a sorted or unsorted (i.e. order left as-is) output - provided that such sorting logic is implemented (which this PR does).
• Gson has better extensibility and performance than org.json. The former allows us to add more options later to the formatter, see GsonBuilder.

Notes:

• I kept simple for backwards compatibility.
• Common test cases for the two implementations have been extracted to a common test class.
• The only limitation of Gson compared to org.json is that there's no option to leave HTML markup as it was in the original input file. Either all HTML characters are escaped, or none. (I.e. no way to keep it mixed in case the input file was mixed.) This is a minor issue in my opinion, but felt important to share.

Change includes:

• Gradle support with indentWithSpaces, sortByKeys, escapeHtml, and version properties
• Unit test updates accordingly, covering added features too
• Documentation updates

[nedtwigg]

Great PR, this will definitely get merged in some form, thanks!

Two points:

1. I think most of the classes in com.diffplug.spotless.json.gson can be made package-private rather than public.

2. You are currently using lots of reflection. That is fine, and I'm happy to merge this PR as-is. But you might want to consider #524

[abelk2]

1. I think most of the classes in com.diffplug.spotless.json.gson can be made package-private rather than public.

Good point, done. Please note that I had to also put GsonStep into the mentioned package so that it still sees the helper classes. For this, a slight modification was also needed in README.md (only a single package level was supported).

2. You are currently using lots of reflection. That is fine, and I'm happy to merge this PR as-is. But you might want to consider Use custom source sets and compile-only dependencies instead of reflection #524

Thank you, I completely missed this one. I could definitely deliver this as a future improvement, but would prefer not to with this PR. I'd like to use this on a corporate project as soon as possible.

[nedtwigg]

We should advertise the compile-only thing better, would #1129 have helped you?

I'd like to use this on a corporate project as soon as possible.

Roger. I'll merge and release once CI completes.

[nedtwigg]

CI failed with a spotlessApply error ;-)

[abelk2]

We should advertise the compile-only thing better, would #1129 have helped you?

Yes, definitely. The contribution guide would be the best place for this info, that's where I looked for it as well.

CI failed with a spotlessApply error ;-)

Oops. sorry for that. Error fixed.

[nedtwigg]

Published in plugin-gradle 6.3.0.

[ZacSweers]

Out of curiosity, why not just use setPrettyPrinting?

[abelk2]

@ZacSweers We need to set a custom JsonWriter so that we can customize the indentation size. The prettyPrinting property has no effect on the overload of toJson we use for this, see Gson.java#L835