diff --git a/README.adoc b/README.adoc index c07ccb723..831ae41ee 100644 --- a/README.adoc +++ b/README.adoc @@ -157,12 +157,12 @@ attributeProvider:: Register an additional provider of attributes. Attribute providers are a means of adding attributes that will not affect the up-to-date status of tasks. epubVersion:: {asciidoctorj-epub-name} version. If not specified asciidoctorj-epub will not be on the classpath. If you plan to use the EPUB backend, then you need to set a version here. -extensions:: Groovy DSL extensions. - Use `extensions` to add one or more extensions. Use `setExtensions` to replace the current set of extensions with a new set. +docExtensions:: Groovy DSL extensions. + Use `docExtensions` to add one or more extensions. Use `setDocExtensions` to replace the current set of extensions with a new set. Extensions can be any kind of object that is serialisable, although in most cases they will be strings or files. If extensions are detached dependencies, they will not be serialised, but rather will be placed on the classpath in order that {asciidoctorj-name} can pick them up automatically. -fatalWarnings: Patterns for {asciidoctorj-name} log messages that shuold be treated as fatal errors. +fatalWarnings: Patterns for {asciidoctorj-name} log messages that should be treated as fatal errors. The list is empty be default. Use `setFatalWarnings` to clear any existing patterns or to decouple a task's configuration from the global configuration. Use `fatalWarnings` to add more patterns. Pass `missingIncludes()` to add the common use-case of missing include files. @@ -911,7 +911,7 @@ plugins { } asciidoctorj { - extensions project(':extension') + docExtensions project(':extension') } ---- @@ -922,13 +922,13 @@ In the less-common case where extension is not supplied via the default configur The next option is to define extensions directly in the build script. This approach is based on the project asciidoctorj-groovy-dsl that allows to define Asciidoctor extensions in Groovy. -An extension is registered via the `extensions` element. +An extension is registered via the `docExtensions` element. [source,groovy] .build.gradle ---- asciidoctorj { - extensions { + docExtensions { block(name: "BIG", contexts: [":paragraph"]) { parent, reader, attributes -> def upperLines = reader.readLines() @@ -949,7 +949,7 @@ Groovy extensions can also be included as files. .build.gradle ---- asciidoctorj { - extensions file('big.groovy') + docExtensions file('big.groovy') } ---- diff --git a/asciidoctor-gradle-jvm-slides/src/main/groovy/org/asciidoctor/gradle/jvm/slides/AsciidoctorJRevealJSTask.groovy b/asciidoctor-gradle-jvm-slides/src/main/groovy/org/asciidoctor/gradle/jvm/slides/AsciidoctorJRevealJSTask.groovy index cae0cca0c..6f4bedfdd 100644 --- a/asciidoctor-gradle-jvm-slides/src/main/groovy/org/asciidoctor/gradle/jvm/slides/AsciidoctorJRevealJSTask.groovy +++ b/asciidoctor-gradle-jvm-slides/src/main/groovy/org/asciidoctor/gradle/jvm/slides/AsciidoctorJRevealJSTask.groovy @@ -152,7 +152,7 @@ class AsciidoctorJRevealJSTask extends AbstractAsciidoctorTask { /** Name one or more reveal.js plugins to activate. * - * Plugins must match bundle names registered in the {@code revealjsPlugins} extensions. + * Plugins must match bundle names registered in the {@code revealjsPlugins} docExtensions. * If selected plugins from a bundle is requires then they can be specified as {@code 'bundleName/pluginName'}. * * @param p List of plugins. Must be convertible to string. @@ -163,7 +163,7 @@ class AsciidoctorJRevealJSTask extends AbstractAsciidoctorTask { /** Name one or more reveal.js plugins to activate. * - * Plugins must match bundle names registered in the {@code revealjsPlugins} extensions. + * Plugins must match bundle names registered in the {@code revealjsPlugins} docExtensions. * If selected plugins from a bundle is requires then they can be specified as {@code 'bundleName/pluginName'}. * * @param p List of plugins. Must be convertible to string. @@ -174,7 +174,7 @@ class AsciidoctorJRevealJSTask extends AbstractAsciidoctorTask { /** Set reveal.js plugins to activate. * - * Plugins must match bundle names registered in the {@code revealjsPlugins} extensions. + * Plugins must match bundle names registered in the {@code revealjsPlugins} docExtensions. * If selected plugins from a bundle is requires then they can be specified as {@code 'bundleName/pluginName'}. * * @param p List of plugins. Must be convertible to string. diff --git a/asciidoctor-gradle-jvm/src/gradleTest/extension-in-subproject/docs-using-configuration/build.gradle b/asciidoctor-gradle-jvm/src/gradleTest/extension-in-subproject/docs-using-configuration/build.gradle index 564e1bdda..b8b2d81ef 100644 --- a/asciidoctor-gradle-jvm/src/gradleTest/extension-in-subproject/docs-using-configuration/build.gradle +++ b/asciidoctor-gradle-jvm/src/gradleTest/extension-in-subproject/docs-using-configuration/build.gradle @@ -13,6 +13,6 @@ asciidoctorj { } asciidoctor { - configurations 'asciidocExt' + docExtensions 'asciidocExt' inProcess JAVA_EXEC } diff --git a/asciidoctor-gradle-jvm/src/gradleTest/extension-in-subproject/docs-using-project-direct/build.gradle b/asciidoctor-gradle-jvm/src/gradleTest/extension-in-subproject/docs-using-project-direct/build.gradle index f2964b0d2..bbb28d3ed 100644 --- a/asciidoctor-gradle-jvm/src/gradleTest/extension-in-subproject/docs-using-project-direct/build.gradle +++ b/asciidoctor-gradle-jvm/src/gradleTest/extension-in-subproject/docs-using-project-direct/build.gradle @@ -5,7 +5,7 @@ repositories { } asciidoctorj { - extensions project(':extension') + docExtensions project(':extension') } asciidoctor { diff --git a/asciidoctor-gradle-jvm/src/intTest/groovy/org/asciidoctor/gradle/jvm/ExtensionsFunctionalSpec.groovy b/asciidoctor-gradle-jvm/src/intTest/groovy/org/asciidoctor/gradle/jvm/ExtensionsFunctionalSpec.groovy index d934f3785..1b514e01e 100644 --- a/asciidoctor-gradle-jvm/src/intTest/groovy/org/asciidoctor/gradle/jvm/ExtensionsFunctionalSpec.groovy +++ b/asciidoctor-gradle-jvm/src/intTest/groovy/org/asciidoctor/gradle/jvm/ExtensionsFunctionalSpec.groovy @@ -48,7 +48,7 @@ class ExtensionsFunctionalSpec extends FunctionalSpecification { model.processMode, model.version, """ asciidoctor { asciidoctorj { - extensions { + docExtensions { block(name: "BIG", contexts: [":paragraph"]) { parent, reader, attributes -> def upperLines = reader.readLines()*.toUpperCase() @@ -92,7 +92,7 @@ asciidoctor { asciidoctor { asciidoctorj { - extensions ''' + docExtensions ''' block(name: 'BIG', contexts: [':paragraph']) { parent, reader, attributes -> def upperLines = reader.readLines() @@ -136,7 +136,7 @@ block('small') { model.processMode, model.version, """ asciidoctor { asciidoctorj { - extensions file('src/docs/asciidoc/blockMacro.groovy') + docExtensions file('src/docs/asciidoc/blockMacro.groovy') } } """) @@ -164,7 +164,7 @@ asciidoctor { getBuildFile( model.processMode, model.version, ''' asciidoctorj { - extensions { + docExtensions { postprocessor { document, output -> return "Hi, Mom" + output } @@ -203,7 +203,7 @@ asciidoctor { model.processMode, model.version, """ asciidoctor { asciidoctorj { - extensions ''' + docExtensions ''' postprocessor { document, output -> if (output.contains("blacklisted")) { diff --git a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/compat/AsciidoctorCompatibilityTask.groovy b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/compat/AsciidoctorCompatibilityTask.groovy index b985751cf..b0fba3a97 100755 --- a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/compat/AsciidoctorCompatibilityTask.groovy +++ b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/compat/AsciidoctorCompatibilityTask.groovy @@ -67,7 +67,7 @@ import static org.ysb33r.grolifant.api.StringUtils.stringize class AsciidoctorCompatibilityTask extends DefaultTask { private static final String PATH_SEPARATOR = OperatingSystem.current().pathSeparator private static - final String MIGRATE_GEMS_MSG = 'When upgrading GEMs, \'requires\' will need to be set via the asciidoctorj project and task extensions. Use setGemPaths method in extension(s) to set GEM paths.' + final String MIGRATE_GEMS_MSG = 'When upgrading GEMs, \'requires\' will need to be set via the asciidoctorj project and task docExtensions. Use setGemPaths method in extension(s) to set GEM paths.' private static final String DEFAULT_BACKEND = AsciidoctorBackend.HTML5.id private boolean baseDirSetToNull @@ -294,7 +294,7 @@ class AsciidoctorCompatibilityTask extends DefaultTask { */ @Deprecated void extensions(Object... exts) { - migrationMessage('extensions', 'Extensions will need to be set via the asciidoctorj project and task extensions') + migrationMessage('docExtensions', 'Extensions will need to be set via the asciidoctorj project and task docExtensions') if (!exts) return // null check asciidoctorExtensions.addAll(exts as List) } @@ -307,7 +307,7 @@ class AsciidoctorCompatibilityTask extends DefaultTask { @SuppressWarnings('ConfusingMethodName') @Deprecated void gemPath(Object... f) { - migrationMessage('gemPath', 'GEM paths will need to be set via the asciidoctorj project and task extensions using the gemPaths method') + migrationMessage('gemPath', 'GEM paths will need to be set via the asciidoctorj project and task docExtensions using the gemPaths method') if (!f) return // null check this.gemPaths.addAll(f as List) } diff --git a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/internal/ExecutorConfiguration.groovy b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/internal/ExecutorConfiguration.groovy index 80e742fc7..1194e95ba 100644 --- a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/internal/ExecutorConfiguration.groovy +++ b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/internal/ExecutorConfiguration.groovy @@ -71,7 +71,7 @@ JRuby: Asciidoctor: ${options.size()} options ${attributes.size()} attributes - ${asciidoctorExtensions?.size() ?: 0} extensions + ${asciidoctorExtensions?.size() ?: 0} docExtensions logDocuments = ${logDocuments}, copyResources = ${copyResources}, safeMode = ${safeModeLevel} """ } diff --git a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AbstractAsciidoctorTask.groovy b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AbstractAsciidoctorTask.groovy index 8d31bcc89..ace4e501c 100644 --- a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AbstractAsciidoctorTask.groovy +++ b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AbstractAsciidoctorTask.groovy @@ -111,12 +111,12 @@ class AbstractAsciidoctorTask extends DefaultTask { * conversion in parallel. * * When running sequential, the worker classloader, Asciidoctor instances - * and Asciidoctor extensions will be shared across all of the conversions. + * and Asciidoctor docExtensions will be shared across all of the conversions. * When running parallel each conversion will be in a separate classloader, * with a new Asciidoctor instance being initialised for every conversion. * * Sequential work might execute slightly faster, but if you have backend-specific - * extensions you might want to consider parallel mode (or use another Asciidoctor + * docExtensions you might want to consider parallel mode (or use another Asciidoctor * task instance). * * Default is parallel. @@ -448,7 +448,7 @@ class AbstractAsciidoctorTask extends DefaultTask { /** Returns all of the specified configurations as a collections of files. * - * If any extensions are dependencies then they will be included here too. + * If any docExtensions are dependencies then they will be included here too. * * @return FileCollection */ @@ -721,7 +721,7 @@ class AbstractAsciidoctorTask extends DefaultTask { */ @Internal protected List getAsciidoctorJExtensions() { - asciidoctorj.extensions + asciidoctorj.docExtensions } /** Obtains a source tree based on patterns. @@ -948,7 +948,7 @@ class AbstractAsciidoctorTask extends DefaultTask { @SuppressWarnings('Instanceof') private FileCollection findDependenciesInExtensions() { - List deps = asciidoctorj.extensions.findAll { + List deps = asciidoctorj.docExtensions.findAll { it instanceof Dependency } as List @@ -957,7 +957,7 @@ class AbstractAsciidoctorTask extends DefaultTask { } if (!closurePaths.empty) { - // Jumping through hoops to make extensions based upon closures to work. + // Jumping through hoops to make docExtensions based upon closures to work. closurePaths.add(getClassLocation(org.gradle.internal.scripts.ScriptOrigin)) closurePaths.addAll(ifNoGroovyAddLocal(deps)) } @@ -1025,7 +1025,7 @@ class AbstractAsciidoctorTask extends DefaultTask { } private List findExtensionClosures() { - asciidoctorj.extensions.findAll { + asciidoctorj.docExtensions.findAll { it instanceof Closure } as List } diff --git a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy index 2c09f4b0c..8dc2b5c01 100644 --- a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy +++ b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJExtension.groovy @@ -20,11 +20,7 @@ import groovy.transform.CompileStatic import org.asciidoctor.gradle.base.AsciidoctorAttributeProvider import org.asciidoctor.gradle.base.SafeMode import org.asciidoctor.gradle.base.Transform -import org.gradle.api.Action -import org.gradle.api.GradleException -import org.gradle.api.NonExtensible -import org.gradle.api.Project -import org.gradle.api.Task +import org.gradle.api.* import org.gradle.api.artifacts.Configuration import org.gradle.api.artifacts.Dependency import org.gradle.api.artifacts.DependencyResolveDetails @@ -43,8 +39,7 @@ import static org.ysb33r.grolifant.api.StringUtils.stringize * * It can be used as both a project and a task extension. * - * @since 2.0 - * @author Schalk W. Cronjé + * @since 2.0* @author Schalk W. Cronjé */ @CompileStatic @SuppressWarnings('MethodCount') @@ -141,7 +136,7 @@ class AsciidoctorJExtension extends AbstractCombinedProjectTaskExtension { * @return {@code true} if JAR should be injected. */ boolean getInjectInternalGuavaJar() { - if(task) { + if (task) { this.injectGuavaJar == null ? extFromProject.injectInternalGuavaJar : this.injectGuavaJar } else { this.injectGuavaJar == null ? GUAVA_REQUIRED_FOR_EXTERNALS : this.injectGuavaJar @@ -178,7 +173,7 @@ class AsciidoctorJExtension extends AbstractCombinedProjectTaskExtension { /** Version of the Groovy Extension DSL that should be used. * - * @return Version of extension DSL or {@code null} if extensions will not be used. + * @return Version of extension DSL or {@code null} if docExtensions will not be used. */ String getGroovyDslVersion() { if (task) { @@ -395,7 +390,7 @@ class AsciidoctorJExtension extends AbstractCombinedProjectTaskExtension { * @return List of providers. Can be empty. Never {@code null}. */ List getAttributeProviders() { - if(task) { + if (task) { this.attributeProviders.empty ? extFromProject.attributeProviders : this.attributeProviders } else { this.attributeProviders @@ -579,20 +574,47 @@ class AsciidoctorJExtension extends AbstractCombinedProjectTaskExtension { configuration } + /** + * @deprecated Use {@link #getDocExtensions} + */ + @Deprecated + List getExtensions() { + warnExtensionsDeprecated('getExtensions','getDocExtensions') + getDocExtensions() + } + + /** + * @deprecated Use {@link #asciidoctorExtensions} + */ + @Deprecated + void extensions(Object... exts) { + warnExtensionsDeprecated('extensions','docExtensions') + docExtensions(exts) + } + + /** + * @deprecated Use {@link #setDocExtensions} + */ + @Deprecated + void setExtensions(Iterable newExtensions) { + warnExtensionsDeprecated('setExtensions','setDocExtensions') + setDocExtensions(newExtensions) + } + /** Return extensionRegistry. * * These extensionRegistry are not registered at this call. That action is left * to the specific task at its execution time. * - * @return + * @return All extensions that should be registered on a conversion. */ - List getExtensions() { + List getDocExtensions() { if (!task || onlyTaskExtensions) { this.asciidoctorExtensions } else if (this.asciidoctorExtensions.empty) { - extFromProject.extensions + extFromProject.docExtensions } else { - extFromProject.extensions + this.asciidoctorExtensions + extFromProject.docExtensions + this.asciidoctorExtensions } } @@ -600,7 +622,7 @@ class AsciidoctorJExtension extends AbstractCombinedProjectTaskExtension { * either contain Asciidoctor Groovy DSL closures or files * with content conforming to the Asciidoctor Groovy DSL. */ - void extensions(Object... exts) { + void docExtensions(Object... exts) { addExtensions(exts as List) } @@ -609,7 +631,7 @@ class AsciidoctorJExtension extends AbstractCombinedProjectTaskExtension { * If this is declared on a task extension all extention from the global * project extension will be ignored. */ - void setExtensions(Iterable newExtensions) { + void setDocExtensions(Iterable newExtensions) { asciidoctorExtensions.clear() addExtensions(newExtensions as List) onlyTaskExtensions = true @@ -801,7 +823,7 @@ class AsciidoctorJExtension extends AbstractCombinedProjectTaskExtension { } } - /** Adds extensions to the existing container. + /** Adds docExtensions to the existing container. * * Also sets the Groovy DSL version if required. * @@ -812,16 +834,16 @@ class AsciidoctorJExtension extends AbstractCombinedProjectTaskExtension { asciidoctorExtensions.addAll(dehydrateExtensions(newExtensions)) } - /** Prepare extensions for serialisation. + /** Prepare docExtensions for serialisation. * * This takes care of dehydrating any closures. * - * @param exts List of extensions - * @return List of extensions suitable for serialization. + * @param exts List of docExtensions + * @return List of docExtensions suitable for serialization. * */ private List dehydrateExtensions(final List exts) { - Transform.toList(exts){ + Transform.toList(exts) { switch (it) { case Closure: ((Closure) it).dehydrate() @@ -842,18 +864,21 @@ class AsciidoctorJExtension extends AbstractCombinedProjectTaskExtension { @SuppressWarnings('Instanceof') private List patternize(final List patterns) { - Transform.toList(patterns){ - (Pattern)(it instanceof Pattern ? it : ~/${stringize(it)}/) + Transform.toList(patterns) { + (Pattern) (it instanceof Pattern ? it : ~/${stringize(it)}/) } } @CompileDynamic @SuppressWarnings('DuplicateStringLiteral') - Closure excludeTransitiveAsciidoctorJ() { + private Closure excludeTransitiveAsciidoctorJ() { return { exclude(group: ASCIIDOCTORJ_GROUP, module: 'asciidoctorj') exclude(group: ASCIIDOCTORJ_GROUP, module: 'asciidoctorj-api') } + } + private void warnExtensionsDeprecated(String oldMethod, String newMethod) { + getProject().logger.warn "${oldMethod} is deprecated and will be removed in 3.0 of this plugin suite. Use ${newMethod} instead" } } diff --git a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/remote/ExecutorBase.groovy b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/remote/ExecutorBase.groovy index fbdf6e3f9..daa875e19 100644 --- a/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/remote/ExecutorBase.groovy +++ b/asciidoctor-gradle-jvm/src/main/groovy/org/asciidoctor/gradle/remote/ExecutorBase.groovy @@ -116,10 +116,10 @@ abstract class ExecutorBase { base.toPath().relativize(target.toPath()).toFile().toString() } - /** Rehydrates extensions that were serialised. + /** Rehydrates docExtensions that were serialised. * * @param registry Asciidoctor GroovyDSL registry instance. - * @param exts List of extensions to rehydrate. + * @param exts List of docExtensions to rehydrate. * @return */ protected List rehydrateExtensions(final Object registry, final List exts) { diff --git a/asciidoctor-gradle-jvm/src/test/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJBasePluginSpec.groovy b/asciidoctor-gradle-jvm/src/test/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJBasePluginSpec.groovy index d95661f35..e88e28a82 100644 --- a/asciidoctor-gradle-jvm/src/test/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJBasePluginSpec.groovy +++ b/asciidoctor-gradle-jvm/src/test/groovy/org/asciidoctor/gradle/jvm/AsciidoctorJBasePluginSpec.groovy @@ -64,7 +64,7 @@ class AsciidoctorJBasePluginSpec extends Specification { AsciidoctorJExtension ext = project.extensions.getByName(AsciidoctorJExtension.NAME) - ext.extensions '1' + ext.docExtensions '1' then: verifyAll { @@ -101,6 +101,5 @@ class AsciidoctorJBasePluginSpec extends Specification { taskExt.version == '1.2.3' taskExt.groovyDslVersion == '4.5.6' } - } } \ No newline at end of file diff --git a/gradle/compatibility-tests.gradle b/gradle/compatibility-tests.gradle index a7d76f69c..cd815dd41 100644 --- a/gradle/compatibility-tests.gradle +++ b/gradle/compatibility-tests.gradle @@ -34,7 +34,6 @@ gradleTest { if (tasks.findByName('intTest')) { mustRunAfter 'intTest' } - enabled = !gradle.startParameter.offline dependsOn ':testfixtures-offline-repo:buildOfflineRepositories'