Package com.diffplug.gradle.spotless

Class FormatExtension

    • Field Detail

      • 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 java.lang.String targetExcludeContentPattern
        The value from which files will be excluded if their content contain it.

      • steps

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

    • Constructor Detail

    • Method Detail

      • provisioner

        protected final Provisioner provisioner()

      • ignoreErrorForStep

        public void ignoreErrorForStep​(java.lang.String stepName)
        Ignores errors in the given step.

      • ignoreErrorForPath

        public void ignoreErrorForPath​(java.lang.String relativePath)
        Ignores errors for the given relative path.

      • isLicenseHeaderStep

        protected boolean isLicenseHeaderStep​(FormatterStep formatterStep)

      • target

        public void target​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.util.function.Function<Provisioner,​FormatterStep> createStepFn)
        Adds a new step that requires a Provisioner.

      • getExistingStepIdx

        protected int getExistingStepIdx​(java.lang.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​(java.lang.String name,
                   groovy.lang.Closure<java.lang.String> formatter)
        Adds a custom step. Receives a string with unix-newlines, must return a string with unix newlines.

      • custom

        public void custom​(java.lang.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​(java.lang.String name,
                    java.lang.CharSequence original,
                    java.lang.CharSequence after)
        Highly efficient find-replace char sequence.

      • replaceRegex

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

      • trimTrailingWhitespace

        public void trimTrailingWhitespace()
        Removes trailing whitespace.

      • endWithNewline

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

      • indentWithSpaces

        public void indentWithSpaces​(int numSpacesPerTab)
        Ensures that the files are indented using spaces.

      • indentWithSpaces

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

      • indentWithTabs

        public void indentWithTabs​(int tabToSpaces)
        Ensures that the files are indented using tabs.

      • indentWithTabs

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

      • nativeCmd

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

      • licenseHeader

        public FormatExtension.LicenseHeaderConfig licenseHeader​(java.lang.String licenseHeader,
                                                         java.lang.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​(java.lang.Object licenseHeaderFile,
                                                             java.lang.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​(java.util.Map<java.lang.String,​java.lang.String> devDependencies)
        Uses exactly the npm packages specified in the map.

      • biome

        public RomeStepConfig<?> 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 RomeStepConfig<?> biome​(java.lang.String version)
        Downloads the given Biome version from the network.

      • rome

        @Deprecated
public RomeStepConfig<?> rome()
        Deprecated.
        Use biome(String).
        Defaults to downloading the default Rome version from the network. To work offline, you can specify the path to the Rome executable via rome().pathToExe(...).

      • rome

        @Deprecated
public RomeStepConfig<?> rome​(java.lang.String version)
        Deprecated.
        Use biome(String).
        Downloads the given Rome version from the network.

      • withinBlocks

        public void withinBlocks​(java.lang.String name,
                         java.lang.String open,
                         java.lang.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​(java.lang.String name,
                                                     java.lang.String open,
                                                     java.lang.String close,
                                                     java.lang.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()
     }
     ...

      • toggleOffOnRegex

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

      • toggleOffOn

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

      • toggleOffOn

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

      • 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.

      • createIndependentApplyTaskLazy

        public TaskProvider<SpotlessApply> createIndependentApplyTaskLazy​(java.lang.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()