From 8a8744261380bd8691acfa88ad9e27516a2b58a5 Mon Sep 17 00:00:00 2001 From: Konrad Windszus Date: Sat, 30 Dec 2023 12:47:52 +0100 Subject: [PATCH 1/2] [MSITE-1000] Introduce parser configuration parameter --- pom.xml | 13 +- .../render/AbstractSiteRenderingMojo.java | 20 ++- .../site/render/ParserConfiguration.java | 117 ++++++++++++++++++ .../ParserConfigurationRetrieverImpl.java | 39 ++++++ .../site/render/ReportDocumentRenderer.java | 1 + .../ParserConfigurationRetrieverImplTest.java | 84 +++++++++++++ 6 files changed, 272 insertions(+), 2 deletions(-) create mode 100644 src/main/java/org/apache/maven/plugins/site/render/ParserConfiguration.java create mode 100644 src/main/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImpl.java create mode 100644 src/test/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImplTest.java diff --git a/pom.xml b/pom.xml index b9d095c4..66f40a1a 100644 --- a/pom.xml +++ b/pom.xml @@ -199,7 +199,7 @@ under the License. 9.4.53.v20231009 2.0.0-M8 - 2.0.0-M16 + 2.0.0-M17-SNAPSHOT 3.5.3 1.7.36 @@ -513,6 +513,17 @@ under the License. + + org.apache.maven.plugins + maven-plugin-plugin + + + https://maven.apache.org/doxia/doxia/doxia-core/apidocs/ + https://maven.apache.org/doxia/doxia-sitetools/doxia-site-renderer/apidocs/ + https://docs.oracle.com/javase/8/docs/api/ + + + org.apache.maven.plugins maven-plugin-report-plugin diff --git a/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java b/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java index 8906cbc8..151ee182 100644 --- a/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java +++ b/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java @@ -94,6 +94,24 @@ public abstract class AbstractSiteRenderingMojo extends AbstractSiteDescriptorMo @Parameter private Map attributes; + /** + * Parser configurations (per Doxia markup source file paths). + * Each entry has the following format + *

+ * 

+     *   <patterns>
+     *     <pattern>glob:**/*.md</pattern><!-- is either glob or regex syntax -->
+     *   </patterns>
+     *   <emitComments>true</emitComments><!-- false by default -->
+     *   <emitAnchorsForIndexableEntries>false</emitAnchorsForIndexableEntries><!-- true by default -->
+     *
+ * + * @since 4.0.0 + * @see java.nio.file.FileSystem#getPathMatcher(String) FileSystem.getPathMatcher(String) for the supported patterns + */ + @Parameter + private List parserConfigurations; + /** * Site renderer. */ @@ -329,7 +347,7 @@ protected SiteRenderingContext createSiteRenderingContext(Locale locale) context.setProcessedContentOutput(processedDir); } } - + context.setParserConfigurationRetriever(new ParserConfigurationRetrieverImpl(parserConfigurations)); return context; } diff --git a/src/main/java/org/apache/maven/plugins/site/render/ParserConfiguration.java b/src/main/java/org/apache/maven/plugins/site/render/ParserConfiguration.java new file mode 100644 index 00000000..4f8a84d3 --- /dev/null +++ b/src/main/java/org/apache/maven/plugins/site/render/ParserConfiguration.java @@ -0,0 +1,117 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.maven.plugins.site.render; + +import java.nio.file.FileSystem; +import java.nio.file.Path; +import java.nio.file.PathMatcher; +import java.util.LinkedList; +import java.util.List; +import java.util.regex.Pattern; +import java.util.stream.Collectors; + +import org.apache.maven.doxia.parser.Parser; + +/** Configuration for a Doxia {@link Parser} (bound to a specific markup source path pattern) **/ +public class ParserConfiguration implements org.apache.maven.doxia.siterenderer.ParserConfiguration { + + /** + * List of patterns in the format described at {@link FileSystem#getPathMatcher(String)}, i.e. {@code :} + * where {@code patterns; + + /** + * List of {@link PathMatcher}s for all of the {@link #patterns}. Lazily populated via {@link FileSystem#getPathMatcher(String)}. + */ + private List matchers; + + private boolean emitComments; + + private boolean emitAnchorsForIndexableEntries; + + public ParserConfiguration() { + patterns = new LinkedList<>(); + matchers = null; + } + + /** + * Switches the feature {@link Parser#setEmitComments(boolean)} either on or off. + * Default is off. + * + * @param emitComments {@code true} to switch it on, otherwise leave it off + * @see Parser#setEmitComments(boolean) + */ + public void setEmitComments(boolean emitComments) { + this.emitComments = emitComments; + } + + /** + * Switches the feature {@link Parser#setEmitAnchorsForIndexableEntries(boolean)} either on or off. + * Default is on. + * + * @param emitAnchorsForIndexableEntries {@code true} to switch it on, otherwise leave it off + * @see Parser#setEmitAnchorsForIndexableEntries(boolean) + */ + public void setEmitAnchorsForIndexableEntries(boolean emitAnchorsForIndexableEntries) { + this.emitAnchorsForIndexableEntries = emitAnchorsForIndexableEntries; + } + + /** + * A pattern in the format described at {@link FileSystem#getPathMatcher(String)}, i.e. {@code :} + * where {@code filePath.getFileSystem().getPathMatcher(p)) + .collect(Collectors.toList()); + } + return matchers.stream().anyMatch(m -> m.matches(filePath)); + } + + @Override + public void accept(Parser parser) { + parser.setEmitComments(emitComments); + // parser.setEmitAnchorsForIndexableEntries(emitAnchorsForIndexableEntries); + } +} diff --git a/src/main/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImpl.java b/src/main/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImpl.java new file mode 100644 index 00000000..a6ce7686 --- /dev/null +++ b/src/main/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImpl.java @@ -0,0 +1,39 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.maven.plugins.site.render; + +import java.nio.file.Path; +import java.util.Collection; +import java.util.Optional; + +import org.apache.maven.doxia.siterenderer.ParserConfigurationRetriever; + +public class ParserConfigurationRetrieverImpl implements ParserConfigurationRetriever { + + private final Collection parserConfigurations; + + public ParserConfigurationRetrieverImpl(Collection parserConfigurations) { + this.parserConfigurations = parserConfigurations; + } + + @Override + public Optional apply(Path filePath) { + return parserConfigurations.stream().filter(c -> c.matches(filePath)).findFirst(); + } +} diff --git a/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java b/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java index c359269d..e30862e1 100644 --- a/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java +++ b/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java @@ -131,6 +131,7 @@ public Sink createSink(File outputDirectory, String outputName) { docRenderingContext.getBasedirRelativePath(), document, docRenderingContext.getParserId(), + docRenderingContext.getParserConfiguration(), // TODO: use another config? docRenderingContext.getExtension(), docRenderingContext.isEditable(), docRenderingContext.getGenerator()); diff --git a/src/test/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImplTest.java b/src/test/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImplTest.java new file mode 100644 index 00000000..2cc80dba --- /dev/null +++ b/src/test/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImplTest.java @@ -0,0 +1,84 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you 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 org.apache.maven.plugins.site.render; + +import java.nio.file.Paths; +import java.util.Arrays; +import java.util.Optional; + +import org.junit.Test; + +import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertThrows; + +public class ParserConfigurationRetrieverImplTest { + + @Test + public void testEmptyConfigurations() { + ParserConfiguration config1 = new ParserConfiguration(); + ParserConfiguration config2 = new ParserConfiguration(); + assertEquals( + Optional.empty(), + new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)).apply(Paths.get("some", "file"))); + } + + @Test + public void testConfigurationWithInvalidPattern() { + ParserConfiguration config1 = new ParserConfiguration(); + config1.addPattern("invalidprefix:*"); + ParserConfigurationRetrieverImpl parserConfigurationRetrieverImpl = + new ParserConfigurationRetrieverImpl(Arrays.asList(config1)); + assertThrows(RuntimeException.class, () -> { + parserConfigurationRetrieverImpl.apply(Paths.get("some", "file")); + }); + } + + @Test + public void testNonMatchingConfigurations() { + ParserConfiguration config1 = new ParserConfiguration(); + config1.addPattern("glob:**/*.md"); + ParserConfiguration config2 = new ParserConfiguration(); + config2.addPattern("regex:.*\\.apt"); + assertEquals( + Optional.empty(), + new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)).apply(Paths.get("some", "file"))); + } + + @Test + public void testNonOverlappingConfigurations() { + ParserConfiguration config1 = new ParserConfiguration(); + config1.addPattern("regex:.*\\.apt"); + ParserConfiguration config2 = new ParserConfiguration(); + config2.addPattern("glob:**/*"); + assertEquals( + Optional.of(config2), + new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)).apply(Paths.get("some", "file"))); + } + + @Test + public void testOverlappingConfigurations() { + ParserConfiguration config1 = new ParserConfiguration(); + config1.addPattern("glob:**/*"); + ParserConfiguration config2 = new ParserConfiguration(); + config2.addPattern("regex:.*"); + assertEquals( + Optional.of(config1), + new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)).apply(Paths.get("some", "file"))); + } +} From 2da5f8ccce95d98a8edea1d9d92d5f23319a427d Mon Sep 17 00:00:00 2001 From: Konrad Windszus Date: Mon, 8 Jan 2024 17:27:48 +0100 Subject: [PATCH 2/2] cleanup --- pom.xml | 2 +- .../site/render/AbstractSiteRenderingMojo.java | 9 +++++---- .../plugins/site/render/ParserConfiguration.java | 12 +++++++----- .../render/ParserConfigurationRetrieverImpl.java | 7 +++++-- .../site/render/ReportDocumentRenderer.java | 1 - .../ParserConfigurationRetrieverImplTest.java | 14 +++++++++----- 6 files changed, 27 insertions(+), 18 deletions(-) diff --git a/pom.xml b/pom.xml index 66f40a1a..e281ac24 100644 --- a/pom.xml +++ b/pom.xml @@ -198,7 +198,7 @@ under the License. 8 9.4.53.v20231009 - 2.0.0-M8 + 2.0.0-M9-SNAPSHOT 2.0.0-M17-SNAPSHOT 3.5.3 1.7.36 diff --git a/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java b/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java index 151ee182..66e89224 100644 --- a/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java +++ b/src/main/java/org/apache/maven/plugins/site/render/AbstractSiteRenderingMojo.java @@ -95,17 +95,18 @@ public abstract class AbstractSiteRenderingMojo extends AbstractSiteDescriptorMo private Map attributes; /** - * Parser configurations (per Doxia markup source file paths). - * Each entry has the following format + * Parser configurations (per matching Doxia markup source file path patterns). + * Each configuration item has the following format: *

* 

      *   <patterns>
-     *     <pattern>glob:**/*.md</pattern><!-- is either glob or regex syntax -->
+     *     <pattern>glob:**/*.md</pattern><!-- is either glob or regex syntax with the according prefix -->
      *   </patterns>
      *   <emitComments>true</emitComments><!-- false by default -->
      *   <emitAnchorsForIndexableEntries>false</emitAnchorsForIndexableEntries><!-- true by default -->
      *
- * + * The configuration is only applied if one of the given patterns matches the Doxia markup source file path. + * The first matching configuration wins (i.e. is applied). * @since 4.0.0 * @see java.nio.file.FileSystem#getPathMatcher(String) FileSystem.getPathMatcher(String) for the supported patterns */ diff --git a/src/main/java/org/apache/maven/plugins/site/render/ParserConfiguration.java b/src/main/java/org/apache/maven/plugins/site/render/ParserConfiguration.java index 4f8a84d3..c48abda9 100644 --- a/src/main/java/org/apache/maven/plugins/site/render/ParserConfiguration.java +++ b/src/main/java/org/apache/maven/plugins/site/render/ParserConfiguration.java @@ -28,7 +28,9 @@ import org.apache.maven.doxia.parser.Parser; -/** Configuration for a Doxia {@link Parser} (bound to a specific markup source path pattern) **/ +/** Configuration for a Doxia {@link Parser} (bound to a specific markup source path pattern) + * @since 4.0.0 + **/ public class ParserConfiguration implements org.apache.maven.doxia.siterenderer.ParserConfiguration { /** @@ -56,7 +58,7 @@ public ParserConfiguration() { /** * Switches the feature {@link Parser#setEmitComments(boolean)} either on or off. - * Default is off. + * Default (for Doxia Sitetools) is off. * * @param emitComments {@code true} to switch it on, otherwise leave it off * @see Parser#setEmitComments(boolean) @@ -67,7 +69,7 @@ public void setEmitComments(boolean emitComments) { /** * Switches the feature {@link Parser#setEmitAnchorsForIndexableEntries(boolean)} either on or off. - * Default is on. + * Default (for Doxia Sitetools) is on. * * @param emitAnchorsForIndexableEntries {@code true} to switch it on, otherwise leave it off * @see Parser#setEmitAnchorsForIndexableEntries(boolean) @@ -110,8 +112,8 @@ public boolean matches(Path filePath) { } @Override - public void accept(Parser parser) { + public void configure(Parser parser) { parser.setEmitComments(emitComments); - // parser.setEmitAnchorsForIndexableEntries(emitAnchorsForIndexableEntries); + parser.setEmitAnchorsForIndexableEntries(emitAnchorsForIndexableEntries); } } diff --git a/src/main/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImpl.java b/src/main/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImpl.java index a6ce7686..93765951 100644 --- a/src/main/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImpl.java +++ b/src/main/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImpl.java @@ -33,7 +33,10 @@ public ParserConfigurationRetrieverImpl(Collection parserCo } @Override - public Optional apply(Path filePath) { - return parserConfigurations.stream().filter(c -> c.matches(filePath)).findFirst(); + public Optional retrieve(Path filePath) { + return parserConfigurations.stream() + .filter(c -> c.matches(filePath)) + .findFirst() + .map(c -> c); } } diff --git a/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java b/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java index e30862e1..c359269d 100644 --- a/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java +++ b/src/main/java/org/apache/maven/plugins/site/render/ReportDocumentRenderer.java @@ -131,7 +131,6 @@ public Sink createSink(File outputDirectory, String outputName) { docRenderingContext.getBasedirRelativePath(), document, docRenderingContext.getParserId(), - docRenderingContext.getParserConfiguration(), // TODO: use another config? docRenderingContext.getExtension(), docRenderingContext.isEditable(), docRenderingContext.getGenerator()); diff --git a/src/test/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImplTest.java b/src/test/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImplTest.java index 2cc80dba..df80ea16 100644 --- a/src/test/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImplTest.java +++ b/src/test/java/org/apache/maven/plugins/site/render/ParserConfigurationRetrieverImplTest.java @@ -35,7 +35,8 @@ public void testEmptyConfigurations() { ParserConfiguration config2 = new ParserConfiguration(); assertEquals( Optional.empty(), - new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)).apply(Paths.get("some", "file"))); + new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)) + .retrieve(Paths.get("some", "file"))); } @Test @@ -45,7 +46,7 @@ public void testConfigurationWithInvalidPattern() { ParserConfigurationRetrieverImpl parserConfigurationRetrieverImpl = new ParserConfigurationRetrieverImpl(Arrays.asList(config1)); assertThrows(RuntimeException.class, () -> { - parserConfigurationRetrieverImpl.apply(Paths.get("some", "file")); + parserConfigurationRetrieverImpl.retrieve(Paths.get("some", "file")); }); } @@ -57,7 +58,8 @@ public void testNonMatchingConfigurations() { config2.addPattern("regex:.*\\.apt"); assertEquals( Optional.empty(), - new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)).apply(Paths.get("some", "file"))); + new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)) + .retrieve(Paths.get("some", "file"))); } @Test @@ -68,7 +70,8 @@ public void testNonOverlappingConfigurations() { config2.addPattern("glob:**/*"); assertEquals( Optional.of(config2), - new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)).apply(Paths.get("some", "file"))); + new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)) + .retrieve(Paths.get("some", "file"))); } @Test @@ -79,6 +82,7 @@ public void testOverlappingConfigurations() { config2.addPattern("regex:.*"); assertEquals( Optional.of(config1), - new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)).apply(Paths.get("some", "file"))); + new ParserConfigurationRetrieverImpl(Arrays.asList(config1, config2)) + .retrieve(Paths.get("some", "file"))); } }