Package com.diffplug.gradle.spotless

Class FormatExtension

java.lang.Object
com.diffplug.gradle.spotless.FormatExtension
Direct Known Subclasses:
Antlr4Extension, BaseGroovyExtension, BaseKotlinExtension, CppExtension, CssExtension, FlexmarkExtension, FreshMarkExtension, GherkinExtension, GoExtension, JavaExtension, JavascriptExtension, JsonExtension, PomExtension, ProtobufExtension, PythonExtension, ScalaExtension, ShellExtension, SqlExtension, TypescriptExtension, YamlExtension
public class FormatExtension extends Object
Adds a spotless{Name}Check and spotless{Name}Apply task.

  • Field Details

    • target

      protected FileCollection target
      The files to be formatted = (target - targetExclude).

    • targetExclude

      protected FileCollection targetExclude
      The files to be formatted = (target - targetExclude).

    • targetExcludeContentPattern

      @Nullable protected String targetExcludeContentPattern
      The value from which files will be excluded if their content contain it.

    • steps

      protected final List<FormatterStep> steps
      The steps that need to be added.

  • Constructor Details

  • Method Details

    • provisioner

      protected final Provisioner provisioner()

    • getLineEndings

      public LineEnding getLineEndings()
      Returns the line endings to use (defaults to SpotlessExtension.getLineEndings().

    • setLineEndings

      public void setLineEndings(LineEnding lineEndings)
      Sets the line endings to use (defaults to SpotlessExtension.getLineEndings().

    • getEncoding

      public Charset getEncoding()
      Returns the encoding to use (defaults to SpotlessExtension.getEncoding().

    • setEncoding

      public void setEncoding(String name)
      Sets the encoding to use (defaults to SpotlessExtension.getEncoding().

    • getRatchetFrom

      public String getRatchetFrom()
      See Also:

    • setRatchetFrom

      public void setRatchetFrom(String ratchetFrom)
      Allows you to override the value from the parent SpotlessExtension.setRatchetFrom(String) for this specific format.

    • ratchetFrom

      public void ratchetFrom(String ratchetFrom)
      See Also:

    • setEncoding

      public void setEncoding(Charset charset)
      Sets the encoding to use (defaults to SpotlessExtension.getEncoding().

    • suppressLintsFor

      public void suppressLintsFor(Action<LintSuppression> lintSuppression)
      Suppresses any lints which meet the supplied criteria.

    • ignoreErrorForStep

      @Deprecated public void ignoreErrorForStep(String stepName)
      Deprecated.
      Use suppressLintsFor(Action) instead.
      Ignores errors in the given step.

    • ignoreErrorForPath

      @Deprecated public void ignoreErrorForPath(String relativePath)
      Deprecated.
      Use suppressLintsFor(Action) instead.
      Ignores errors for the given relative path.

    • encoding

      public void encoding(String charset)
      Sets encoding to use (defaults to SpotlessExtension.getEncoding()).

    • isLicenseHeaderStep

      protected boolean isLicenseHeaderStep(FormatterStep formatterStep)

    • target

      public void target(Object... targets)
      Sets which files should be formatted. Files to be formatted = (target - targetExclude).

      When this method is called multiple times, only the last call has any effect.

      FileCollections pass through raw. Strings are treated as the 'include' arg to fileTree, with project.rootDir as the dir. List are treated as the 'includes' arg to fileTree, with project.rootDir as the dir. Anything else gets passed to getProject().files().

      If you pass any strings that start with "**\/*", this method will automatically filter out "build", ".gradle", and ".git" folders.

    • targetExclude

      public void targetExclude(Object... targets)
      Sets which files will be excluded from formatting. Files to be formatted = (target - targetExclude).

      When this method is called multiple times, only the last call has any effect.

      FileCollections pass through raw. Strings are treated as the 'include' arg to fileTree, with project.rootDir as the dir. List are treated as the 'includes' arg to fileTree, with project.rootDir as the dir. Anything else gets passed to getProject().files().

    • targetExcludeIfContentContains

      public void targetExcludeIfContentContains(String string)
      Excludes all files whose content contains string.

      When this method is called multiple times, only the last call has any effect.

    • targetExcludeIfContentContainsRegex

      public void targetExcludeIfContentContainsRegex(String regex)
      Excludes all files whose content contains the given regex.

      When this method is called multiple times, only the last call has any effect.

    • parseTarget

      protected final FileCollection parseTarget(Object target)
      FileCollections pass through raw. Strings are treated as the 'include' arg to fileTree, with project.rootDir as the dir. List are treated as the 'includes' arg to fileTree, with project.rootDir as the dir. Anything else gets passed to getProject().files().

    • addStep

      public void addStep(FormatterStep newStep)
      Adds a new step.

    • addStep

      public void addStep(Function<Provisioner,FormatterStep> createStepFn)
      Adds a new step that requires a Provisioner.

    • getExistingStepIdx

      protected int getExistingStepIdx(String stepName)
      Returns the index of the existing step with the given name, or -1 if no such step exists.

    • replaceStep

      protected void replaceStep(FormatterStep replacementStep)
      Replaces the given step.

    • clearSteps

      public void clearSteps()
      Clears all of the existing steps.

    • bumpThisNumberIfACustomStepChanges

      public void bumpThisNumberIfACustomStepChanges(int number)
      An optional performance optimization if you are using any of the custom methods. If you aren't explicitly calling custom, then this method has no effect.

      Spotless tracks what files have changed from run to run, so that it can run faster by only checking files which have changed, or whose formatting steps have changed. If you use the custom methods, then Gradle can never mark your files as up-to-date, because it can't know if perhaps the behavior of your custom function has changed.

      If you set bumpThisNumberIfACustomStepChanges( <some number> ), then spotless will assume that the custom rules have not changed if the number has not changed. If a custom rule does change, then you must bump the number so that spotless will know that it must recheck the files it has already checked.

    • custom

      public void custom(String name, groovy.lang.Closure<String> formatter)
      Adds a custom step. Receives a string with unix-newlines, must return a string with unix newlines.

    • custom

      public void custom(String name, FormatterFunc formatter)
      Adds a custom step. Receives a string with unix-newlines, must return a string with unix newlines.

    • replace

      public void replace(String name, CharSequence original, CharSequence after)
      Highly efficient find-replace char sequence.

    • replaceRegex

      public void replaceRegex(String name, String regex, String replacement)
      Highly efficient find-replace regex.

    • forbidRegex

      public void forbidRegex(String name, String regex, String lintDetail)
      A regex which generates a lint.

    • trimTrailingWhitespace

      public void trimTrailingWhitespace()
      Removes trailing whitespace.

    • endWithNewline

      public void endWithNewline()
      Ensures that files end with a single newline.

    • leadingTabsToSpaces

      public void leadingTabsToSpaces(int spacesPerTab)
      Ensures that the files are indented using spaces.

    • indentWithSpaces

      @Deprecated public void indentWithSpaces(int numSpacesPerTab)
      Deprecated.

    • leadingTabsToSpaces

      public void leadingTabsToSpaces()
      Ensures that the files are indented using spaces.

    • indentWithSpaces

      @Deprecated public void indentWithSpaces()
      Deprecated.

    • leadingSpacesToTabs

      public void leadingSpacesToTabs(int spacesPerTab)
      Ensures that the files are indented using tabs.

    • indentWithTabs

      @Deprecated public void indentWithTabs(int tabToSpaces)
      Deprecated.

    • leadingSpacesToTabs

      public void leadingSpacesToTabs()
      Ensures that the files are indented using tabs.

    • indentWithTabs

      @Deprecated public void indentWithTabs()
      Deprecated.

    • nativeCmd

      public void nativeCmd(String name, String pathToExe, List<String> arguments)
      Ensures formatting of files via native binary.

    • licenseHeader

      public FormatExtension.LicenseHeaderConfig licenseHeader(String licenseHeader, String delimiter)
      Parameters:
      licenseHeader - Content that should be at the top of every file.
      delimiter - Spotless will look for a line that starts with this regular expression pattern to know what the "top" is.

    • licenseHeaderFile

      public FormatExtension.LicenseHeaderConfig licenseHeaderFile(Object licenseHeaderFile, String delimiter)
      Parameters:
      licenseHeaderFile - Content that should be at the top of every file.
      delimiter - Spotless will look for a line that starts with this regular expression pattern to know what the "top" is.

    • prettier

      public FormatExtension.PrettierConfig prettier()
      Uses the default version of prettier.

    • prettier

      public FormatExtension.PrettierConfig prettier(String version)
      Uses the specified version of prettier.

    • prettier

      public FormatExtension.PrettierConfig prettier(Map<String,String> devDependencies)
      Uses exactly the npm packages specified in the map.

    • biome

      public BiomeStepConfig<?> biome()
      Defaults to downloading the default Biome version from the network. To work offline, you can specify the path to the Biome executable via biome().pathToExe(...).

    • biome

      public BiomeStepConfig<?> biome(String version)
      Downloads the given Biome version from the network.

    • clangFormat

      public FormatExtension.ClangFormatConfig clangFormat()
      Uses the default version of clang-format.

    • clangFormat

      public FormatExtension.ClangFormatConfig clangFormat(String version)
      Uses the specified version of clang-format.

    • eclipseWtp

      public FormatExtension.EclipseWtpConfig eclipseWtp(com.diffplug.spotless.extra.wtp.EclipseWtpFormatterStep type)

    • eclipseWtp

      public FormatExtension.EclipseWtpConfig eclipseWtp(com.diffplug.spotless.extra.wtp.EclipseWtpFormatterStep type, String version)

    • idea

      public FormatExtension.IdeaConfig idea()

    • withinBlocks

      public void withinBlocks(String name, String open, String close, Action<FormatExtension> configure)
       spotless {
   format 'examples', {
     target '*.md'
     withinBlocks 'javascript examples', '\n```javascript\n', '\n```\n', {
       prettier().config(['parser': 'javascript'])
     }
     ...

    • withinBlocks

      public <T extends FormatExtension> void withinBlocks(String name, String open, String close, Class<T> clazz, Action<T> configure)
      Same as withinBlocks(String, String, String, Action), except you can specify any language-specific subclass of FormatExtension to get language-specific steps. 
       spotless {
   format 'examples', {
     target '*.md'
     withinBlocks 'java examples', '\n```java\n', '\n```\n', com.diffplug.gradle.spotless.JavaExtension, {
       googleJavaFormat()
       formatAnnotations()
     }
     ...

    • withinBlocksRegex

      public void withinBlocksRegex(String name, String regex, Action<FormatExtension> configure)
      Same as withinBlocks(String, String, String, Action), except instead of an open/close pair, you specify a regex with exactly one capturing group.

    • withinBlocksRegex

      public <T extends FormatExtension> void withinBlocksRegex(String name, String regex, Class<T> clazz, Action<T> configure)
      Same as withinBlocksRegex(String, String, Action), except you can specify any language-specific subclass of FormatExtension to get language-specific steps.

    • toggleOffOnRegex

      public void toggleOffOnRegex(String regex)
      Given a regex with *exactly one capturing group*, disables formatting inside that captured group.

    • toggleOffOn

      public void toggleOffOn(String off, String on)
      Disables formatting between the given tags.

    • toggleOffOn

      public void toggleOffOn()
      Disables formatting between spotless:off and spotless:on.

    • toggleOffOnDisable

      public void toggleOffOnDisable()
      Undoes all previous calls to toggleOffOn() and toggleOffOn(String, String).

    • setupTask

      protected void setupTask(SpotlessTask task)
      Sets up a format task according to the values in this extension.

    • getProject

      protected Project getProject()
      Returns the project that this extension is attached to.

    • createIndependentApplyTask

      public SpotlessApply createIndependentApplyTask(String taskName)
      Eager version of createIndependentApplyTaskLazy(String)

    • createIndependentApplyTaskLazy

      public TaskProvider<SpotlessApply> createIndependentApplyTaskLazy(String taskName)
      Creates an independent SpotlessApply for (very) unusual circumstances.

      Most users will not want this method. In the rare case that you want to create a SpotlessApply which is independent of the normal Spotless machinery, this will let you do that.

      The returned task will not be hooked up to the global spotlessApply, and there will be no corresponding check task.

      The task name must not end with `Apply`.

      NOTE: does not respect the rarely-used spotlessFiles property.

    • noDefaultTargetException

      protected GradleException noDefaultTargetException()