feat: clarify indent format option api (#2350 fixes #794)

Author: nedtwigg

plugin-gradle/CHANGES.md

@@ -11,6 +11,7 @@ We adhere to the [keepachangelog](https://keepachangelog.com/en/1.0.0/) format (
 ### Fixed
 * You can now use `removeUnusedImports` and `googleJavaFormat` at the same time again. (fixes [#2159](https://github.com/diffplug/spotless/issues/2159))
 * The default list of type annotations used by `formatAnnotations` now includes Jakarta Validation's `Valid` and constraints validations (fixes [#2334](https://github.com/diffplug/spotless/issues/2334))
+* `indentWith[Spaces|Tabs]` has been deprecated in favor of `leadingTabsToSpaces` and `leadingSpacesToTabs`. ([#2350](https://github.com/diffplug/spotless/pull/2350) fixes [#794](https://github.com/diffplug/spotless/issues/794))
 
 ## [7.0.0.BETA4] - 2024-10-24
 ### Added

plugin-gradle/README.md

@@ -109,7 +109,7 @@ spotless {
 
  // define the steps to apply to those files
  trimTrailingWhitespace()
- indentWithTabs() // or spaces. Takes an integer argument if you don't like 4
+ leadingSpacesToTabs() // or leadingTabsToSpaces. Takes an integer argument if you don't like 4
  endWithNewline()
  }
  java {

plugin-gradle/src/main/java/com/diffplug/gradle/spotless/FormatExtension.java

@@ -47,6 +47,8 @@
 import org.gradle.api.plugins.BasePlugin;
 import org.gradle.api.tasks.TaskProvider;
 import org.gradle.util.GradleVersion;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import com.diffplug.common.base.Preconditions;
 import com.diffplug.spotless.FormatterFunc;
@@ -77,6 +79,9 @@
 
 /** Adds a {@code spotless{Name}Check} and {@code spotless{Name}Apply} task. */
 public class FormatExtension {
+
+private static final Logger logger = LoggerFactory.getLogger(FormatExtension.class);
+
 final SpotlessExtension spotless;
 final List<Action<FormatExtension>> lazyActions = new ArrayList<>();
 
@@ -505,25 +510,53 @@ public void endWithNewline() {
 }
 
 /** Ensures that the files are indented using spaces. */
+public void leadingTabsToSpaces(int spacesPerTab) {
+addStep(IndentStep.Type.SPACE.create(spacesPerTab));
+}
+
+@Deprecated
 public void indentWithSpaces(int numSpacesPerTab) {
-addStep(IndentStep.Type.SPACE.create(numSpacesPerTab));
+logDeprecation("indentWithSpaces", "leadingTabsToSpaces");
+leadingTabsToSpaces(numSpacesPerTab);
 }
 
 /** Ensures that the files are indented using spaces. */
-public void indentWithSpaces() {
+public void leadingTabsToSpaces() {
 addStep(IndentStep.Type.SPACE.create());
 }
 
+@Deprecated
+public void indentWithSpaces() {
+logDeprecation("indentWithSpaces", "leadingTabsToSpaces");
+leadingTabsToSpaces();
+}
+
 /** Ensures that the files are indented using tabs. */
+public void leadingSpacesToTabs(int spacesPerTab) {
+addStep(IndentStep.Type.TAB.create(spacesPerTab));
+}
+
+@Deprecated
 public void indentWithTabs(int tabToSpaces) {
-addStep(IndentStep.Type.TAB.create(tabToSpaces));
+logDeprecation("indentWithTabs", "leadingSpacesToTabs");
+leadingSpacesToTabs(tabToSpaces);
 }
 
 /** Ensures that the files are indented using tabs. */
-public void indentWithTabs() {
+public void leadingSpacesToTabs() {
 addStep(IndentStep.Type.TAB.create());
 }
 
+@Deprecated
+public void indentWithTabs() {
+logDeprecation("indentWithTabs", "leadingSpacesToTabs");
+leadingSpacesToTabs();
+}
+
+private static void logDeprecation(String methodName, String replacement) {
+logger.warn("'{}' is deprecated, use '{}' in your gradle build script instead.", methodName, replacement);
+}
+
 /** Ensures formatting of files via native binary. */
 public void nativeCmd(String name, String pathToExe, List<String> arguments) {
 addStep(NativeCmdStep.create(name, new File(pathToExe), arguments));

plugin-gradle/src/test/java/com/diffplug/gradle/spotless/IndentIntegrationTest.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2021-2024 DiffPlug
+ *
+ * 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.diffplug.gradle.spotless;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.io.IOException;
+import java.util.stream.Stream;
+
+import org.gradle.testkit.runner.BuildResult;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.junit.jupiter.params.provider.ValueSource;
+
+class IndentIntegrationTest extends GradleIntegrationHarness {
+
+@ParameterizedTest
+@ValueSource(strings = {"indentWithSpaces", "indentWithTabs"})
+void oldIndentApiLogsDeprecationWarning(String indentationMethodName) throws IOException {
+BuildResult result = runIndentFormatter(indentationMethodName);
+assertThat(result.getOutput()).containsPattern(".*" + indentationMethodName + ".*deprecated.*");
+}
+
+@ParameterizedTest
+@ValueSource(strings = {"leadingTabsToSpaces", "leadingSpacesToTabs"})
+void newIndentApiDoesNotLogDeprecationWarning(String indentationMethodName) throws IOException {
+BuildResult result = runIndentFormatter(indentationMethodName);
+assertThat(result.getOutput()).doesNotContainPattern(".*" + indentationMethodName + ".*deprecated.*");
+}
+
+@ParameterizedTest(name = "{0}")
+@MethodSource("indentationCombinations")
+void indentationCombinations(String testName, String indentationMethodName, String actualResource, String expectedResultResource) throws IOException {
+runIndentFormatter(indentationMethodName, actualResource);
+assertFile("test.txt").sameAsResource(expectedResultResource);
+}
+
+private static Stream<Arguments> indentationCombinations() {
+return Stream.of(
+// new API
+Arguments.of("tabsToTabs", "leadingSpacesToTabs", "indent/IndentedWithTab.test", "indent/IndentedWithTab.test"),
+Arguments.of("spacesToSpaces", "leadingTabsToSpaces", "indent/IndentedWithSpace.test", "indent/IndentedWithSpace.test"),
+Arguments.of("spacesToTabs", "leadingSpacesToTabs", "indent/IndentedWithSpace.test", "indent/IndentedWithTab.test"),
+Arguments.of("tabsToSpaces", "leadingTabsToSpaces", "indent/IndentedWithTab.test", "indent/IndentedWithSpace.test"),
+Arguments.of("mixedToTabs", "leadingSpacesToTabs", "indent/IndentedMixed.test", "indent/IndentedWithTab.test"),
+Arguments.of("mixedToSpaces", "leadingTabsToSpaces", "indent/IndentedMixed.test", "indent/IndentedWithSpace.test"),
+// legacy API
+Arguments.of("legacy: tabsToTabs", "indentWithTabs", "indent/IndentedWithTab.test", "indent/IndentedWithTab.test"),
+Arguments.of("legacy: spacesToSpaces", "indentWithSpaces", "indent/IndentedWithSpace.test", "indent/IndentedWithSpace.test"),
+Arguments.of("legacy: spacesToTabs", "indentWithTabs", "indent/IndentedWithSpace.test", "indent/IndentedWithTab.test"),
+Arguments.of("legacy: tabsToSpaces", "indentWithSpaces", "indent/IndentedWithTab.test", "indent/IndentedWithSpace.test"),
+Arguments.of("legacy: mixedToTabs", "indentWithTabs", "indent/IndentedMixed.test", "indent/IndentedWithTab.test"),
+Arguments.of("legacy: mixedToSpaces", "indentWithSpaces", "indent/IndentedMixed.test", "indent/IndentedWithSpace.test"));
+}
+
+private BuildResult runIndentFormatter(String indentationMethodName) throws IOException {
+return runIndentFormatter(indentationMethodName, "indent/IndentedMixed.test");
+}
+
+private BuildResult runIndentFormatter(String indentationMethodName, String resourceFile) throws IOException {
+setFile("build.gradle").toLines(
+"plugins {",
+" id 'com.diffplug.spotless'",
+"}",
+"spotless {",
+" format 'test', {",
+" target '**/*.txt'",
+" " + indentationMethodName + "()",
+" }",
+"}");
+setFile("test.txt").toResource(resourceFile);
+BuildResult result = gradleRunner().withArguments("spotlessApply").build();
+return result;
+}
+
+}

testlib/src/main/resources/indent/IndentedMixed.test

@@ -0,0 +1,37 @@
+package com.github.youribonnaffe.gradle.format;
+
+import java.util.function.Function;
+
+/**
+ * Test class.
+ */
+public class Java8Test {
+ /**
+ * Test method.
+ */
+ public void doStuff() throws Exception {
+ Function<String, Integer> example = Integer::parseInt;
+ example.andThen(val -> {
+ return val + 2;
+ } );
+ SimpleEnum val = SimpleEnum.A;
+ switch (val) {
+ case A:
+ break;
+ case B:
+ break;
+ case C:
+ break;
+ default:
+ throw new Exception();
+ }
+ }
+
+/** Test enum
+* with weirdly formatted javadoc
+* which IndentStep should not change
+*/
+public enum SimpleEnum {
+A, B, C;
+}
+}