Update changelogs and documentation

diffplug · Jul 18, 2023 · 98943c3 · 98943c3
1 parent 43a8372
commit 98943c3
Show file tree

Hide file tree

Showing 6 changed files with 72 additions and 4 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -10,6 +10,8 @@ This document is intended for Spotless developers.
 We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `1.27.0`).
 
 ## [Unreleased]
+### Added
+* Add an `applyJsonPatch` step to `json` formatter configurations. This allows patching of JSON documents using [JSON Patches](https://jsonpatch.com). ([#1753](https://github.com/diffplug/spotless/pull/1753))
 
 ## [2.40.0] - 2023-07-17
 ### Added

diff --git a/README.md b/README.md
@@ -89,6 +89,7 @@ lib('java.CleanthatJavaStep')                    +'{{yes}}       | {{yes}}
 lib('json.gson.GsonStep')                        +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
 lib('json.JacksonJsonStep')                      +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
 lib('json.JsonSimpleStep')                       +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
+lib('json.ApplyJsonPatchStep')                   +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
 lib('kotlin.KtLintStep')                         +'{{yes}}       | {{yes}}      | {{yes}}      | {{no}}  |',
 lib('kotlin.KtfmtStep')                          +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
 lib('kotlin.DiktatStep')                         +'{{yes}}       | {{yes}}      | {{no}}       | {{no}}  |',
@@ -140,6 +141,7 @@ lib('yaml.JacksonYamlStep')                      +'{{yes}}       | {{yes}}
 | [`json.gson.GsonStep`](lib/src/main/java/com/diffplug/spotless/json/gson/GsonStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
 | [`json.JacksonJsonStep`](lib/src/main/java/com/diffplug/spotless/json/JacksonJsonStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
 | [`json.JsonSimpleStep`](lib/src/main/java/com/diffplug/spotless/json/JsonSimpleStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
+| [`json.ApplyJsonPatchStep`](lib/src/main/java/com/diffplug/spotless/json/ApplyJsonPatchStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
 | [`kotlin.KtLintStep`](lib/src/main/java/com/diffplug/spotless/kotlin/KtLintStep.java) | :+1:       | :+1:      | :+1:      | :white_large_square:  |
 | [`kotlin.KtfmtStep`](lib/src/main/java/com/diffplug/spotless/kotlin/KtfmtStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |
 | [`kotlin.DiktatStep`](lib/src/main/java/com/diffplug/spotless/kotlin/DiktatStep.java) | :+1:       | :+1:      | :white_large_square:       | :white_large_square:  |

diff --git a/plugin-gradle/CHANGES.md b/plugin-gradle/CHANGES.md
@@ -3,6 +3,8 @@
 We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `3.27.0`).
 
 ## [Unreleased]
+### Added
+* Add an `applyJsonPatch` step to `json` formatter configurations. This allows patching of JSON documents using [JSON Patches](https://jsonpatch.com). ([#1753](https://github.com/diffplug/spotless/pull/1753))
 
 ## [6.20.0] - 2023-07-17
 ### Added

diff --git a/plugin-gradle/README.md b/plugin-gradle/README.md
@@ -811,6 +811,7 @@ spotless {
     gson()                                // has its own section below
     jackson()                             // has its own section below
     rome()                                // has its own section below
+    applyJsonPatch([])                    // has its own section below
   }
 }
 ```
@@ -872,6 +873,49 @@ spotless {
 }
 ```
 
+### applyJsonPatch
+
+Uses [zjsonpatch](https://github.com/flipkart-incubator/zjsonpatch) to apply [JSON Patches](https://jsonpatch.com/) as per [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902/) to JSON documents.
+
+This enables you to add, replace or remove properties at locations in the JSON document that you specify using [JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901/).
+
+In Spotless Gradle, these JSON patches are represented as a `List<Map<String, Object>>`, or a list of patch operations.
+
+Each patch operation must be a map with the following properties:
+
+* `"op"` - the operation to apply, one of `"replace"`, `"add"` or `"remove"`.
+* `"path"` - a JSON Pointer string, for example `"/foo"`
+* `"value"` - the value to `"add"` or `"replace"` at the specified path. Not needed for `"remove"` operations.
+
+For example, to apply the patch from the [JSON Patch homepage](https://jsonpatch.com/#the-patch):
+
+```gradle
+spotless {
+  json {
+    target 'src/**/*.json'
+    applyJsonPatch([
+      [op: 'replace', path: '/baz', value: 'boo'],
+      [op: 'add', path: '/hello', value: ['world']],
+      [op: 'remove', path: '/foo']
+    ])
+  }
+}
+```
+
+Or using the Kotlin DSL:
+
+```kotlin
+spotless {
+  json {
+    target("src/**/*.json")
+    applyJsonPatch(listOf(
+      mapOf("op" to "replace", "path" to "/baz", "value" to "boo"),
+      mapOf("op" to "add", "path" to "/hello", "value" to listOf("world")),
+      mapOf("op" to "remove", "path" to "/foo")
+    ))
+  }
+}
+```
 
 ## YAML
 

diff --git a/plugin-maven/CHANGES.md b/plugin-maven/CHANGES.md
@@ -3,6 +3,8 @@
 We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (starting after version `1.27.0`).
 
 ## [Unreleased]
+### Added
+* Add an `applyJsonPatch` step to `json` formatter configurations. This allows patching of JSON documents using [JSON Patches](https://jsonpatch.com). ([#1753](https://github.com/diffplug/spotless/pull/1753))
 
 ## [2.38.0] - 2023-07-17
 ### Added

diff --git a/plugin-maven/README.md b/plugin-maven/README.md
@@ -897,10 +897,11 @@ For details, see the [npm detection](#npm-detection), [`.npmrc` detection](#npmr
       <include>src/**/*.json</include>
     </includes>
 
-    <simple />    <!-- has its own section below -->
-    <gson />      <!-- has its own section below -->
-    <jackson />   <!-- has its own section below -->
-    <rome />      <!-- has its own section below -->
+    <simple />         <!-- has its own section below -->
+    <gson />           <!-- has its own section below -->
+    <jackson />        <!-- has its own section below -->
+    <rome />           <!-- has its own section below -->
+    <applyJsonPatch /> <!-- has its own section below -->
   </json>
 </configuration>
 ```
@@ -957,6 +958,21 @@ Uses Jackson for formatting.
 
 <a name="applying-prettier-to-javascript--flow--typescript--css--scss--less--jsx--graphql--yaml--etc"></a>
 
+### applyJsonPatch
+
+Uses [zjsonpatch](https://github.com/flipkart-incubator/zjsonpatch) to apply [JSON Patches](https://jsonpatch.com/) as per [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902/) to JSON documents.
+
+This enables you to add, replace or remove properties at locations in the JSON document that you specify using [JSON Pointers](https://datatracker.ietf.org/doc/html/rfc6901/).
+
+For example, to apply the patch from the [JSON Patch homepage](https://jsonpatch.com/#the-patch):
+
+```xml
+<applyJsonPatch>[
+  { "op": "replace", "path": "/baz", "value": "boo" },
+  { "op": "add", "path": "/hello", "value": ["world"] },
+  { "op": "remove", "path": "/foo" }
+]</applyJsonPatch>
+```
 
 ## YAML