fix: rework naming and improve FrontMatterParser interface

Author: zyxist

README.md

@@ -411,7 +411,7 @@ document start here
 Use class `YamlFrontMatterExtension` in artifact `commonmark-ext-yaml-front-matter`. To fetch metadata, use `YamlFrontMatterVisitor`:
 
 ```java
-import org.commonmark.ext.front.matter.extractor.YamlContentExtractor;
+import org.commonmark.ext.front.matter.parser.RawContentParser;
 
 List<Extension> extensions = List.of(YamlFrontMatterExtension.create());
 Parser parser = Parser.builder()
@@ -422,22 +422,22 @@ Node document = parser.parse(markdownDocument);
 Map<String, List<String>> frontMatter = YamlFrontMatterVisitor.readData(document);
 ```
 
-Alternatively, you can use initialize the extension with `YamlContentExtractor` that saves the YAML front matter content
-as a string for further processing with other tools:
+Alternatively, you can use initialize the extension with `RawContentParser` to capture the entire front matter as a
+string for further processing with other tools:
 
 ```java
-import org.commonmark.ext.front.matter.extractor.YamlContentExtractor;
+import org.commonmark.ext.front.matter.parser.RawContentParser;
 
-List<Extension> extensions = List.of(YamlFrontMatterExtension.create(new YamlContentExtractor.Factory()));
+List<Extension> extensions = List.of(YamlFrontMatterExtension.create(new RawContentParser.Factory()));
 Parser parser = Parser.builder()
     .extensions(extensions)
     .build();
 
 Node document = parser.parse(markdownDocument);
-String frontMatter = YamlFrontMatterVisitor.readContent(document);
+String frontMatter = YamlFrontMatterVisitor.readRawContent(document);
 ```
 
-You can also write a custom extractor by implementing `YamlFrontMatterExtractor` interface.
+You can also write a custom front matter parser by implementing `FrontMatterParser` interface.
 
 ### Image Attributes
 

commonmark-ext-yaml-front-matter/src/main/java/org/commonmark/ext/front/matter/FrontMatterParser.java

@@ -0,0 +1,33 @@
+package org.commonmark.ext.front.matter;
+
+import org.commonmark.parser.SourceLine;
+
+/**
+ * Parses the content of the front matter block between `---` separators.
+ * The implementations should add at least 1 child node to
+ * {@link YamlFrontMatterBlock} to store the result of the parsing.
+ */
+public interface FrontMatterParser {
+    void onNextLine(YamlFrontMatterBlock block, SourceLine line);
+
+    /**
+     * Notifies about finding the line with the ending separator (`---` or `...`, without
+     * initial whitespace). Advanced parsers may be able to determine that the separator
+     * is a part of the single-/double-quoted multiline string and return {@link SeparatorRole#CONTENT}
+     * to include it in the front matter content. In this case, front matter parsing continues until
+     * finding another separator. To end the parsing, return {@link SeparatorRole#BLOCK_END}.
+     *
+     * @param block Main block node
+     * @param separator `---` or `...`
+     * @return Separator role: block end or the part of the front matter content
+     */
+    SeparatorRole onEndingSeparator(YamlFrontMatterBlock block, SourceLine separator);
+
+    interface Factory {
+        FrontMatterParser create();
+    }
+
+    enum SeparatorRole {
+        BLOCK_END, CONTENT
+    }
+}

commonmark-ext-yaml-front-matter/src/main/java/org/commonmark/ext/front/matter/YamlFrontMatterExtension.java

@@ -3,8 +3,8 @@
 import java.util.Objects;
 import java.util.Set;
 import org.commonmark.Extension;
-import org.commonmark.ext.front.matter.extractor.YamlContentExtractor;
-import org.commonmark.ext.front.matter.extractor.YamlDataExtractor;
+import org.commonmark.ext.front.matter.parser.RawContentParser;
+import org.commonmark.ext.front.matter.parser.YamlSubsetParser;
 import org.commonmark.ext.front.matter.internal.YamlFrontMatterBlockParser;
 import org.commonmark.ext.front.matter.internal.YamlFrontMatterMarkdownNodeRenderer;
 import org.commonmark.node.Node;
@@ -22,24 +22,24 @@
  * org.commonmark.parser.Parser.Builder#extensions(Iterable)}, {@link
  * HtmlRenderer.Builder#extensions(Iterable)}).
  *
- * <p>By default, the extension parses the subset of YAML with a built-int parser.
+ * <p>By default, the extension parses the subset of YAML with a built-int {@link YamlSubsetParser}.
  * The parsed metadata is turned into {@link YamlFrontMatterNode}. You can access
  * the metadata using {@link YamlFrontMatterVisitor#readData(Node)}.
  *
- * <p>Alternatively, you can create the extension with {@link YamlContentExtractor.Factory}.
- * It turns the YAML front matter into {@link YamlFrontMatterContent} node, which stores
- * the front matter content as a simple string. You can access the content with
- * {@link YamlFrontMatterVisitor#readContent(Node)} to process it with other tools.
+ * <p>Alternatively, you can create the extension with {@link RawContentParser.Factory}.
+ * It turns the YAML front matter into {@link YamlFrontMatterRawContent} node, which stores
+ * the entire front matter as a string. You can access the content with
+ * {@link YamlFrontMatterVisitor#readRawContent(Node)} to process it with other tools.
  *
- * <p>To create a custom YAML front matter extractor, implement {@link YamlFrontMatterExtractor}
- * interface and the corresponding factory.
+ * <p>Implement {@link FrontMatterParser} interface and the corresponding factory to
+ * parse the front matter with a custom parser.
  */
 public class YamlFrontMatterExtension
         implements Parser.ParserExtension, MarkdownRenderer.MarkdownRendererExtension {
 
-    private final YamlFrontMatterExtractor.Factory yamlExtractorFactory;
+    private final FrontMatterParser.Factory yamlExtractorFactory;
 
-    private YamlFrontMatterExtension(YamlFrontMatterExtractor.Factory yamlExtractorFactory) {
+    private YamlFrontMatterExtension(FrontMatterParser.Factory yamlExtractorFactory) {
         this.yamlExtractorFactory = Objects.requireNonNull(yamlExtractorFactory);
     }
 
@@ -49,10 +49,10 @@ public void extend(Parser.Builder parserBuilder) {
     }
 
     public static Extension create() {
-        return create(new YamlDataExtractor.Factory());
+        return create(new YamlSubsetParser.Factory());
     }
 
-    public static Extension create(YamlFrontMatterExtractor.Factory extractor) {
+    public static Extension create(FrontMatterParser.Factory extractor) {
         return new YamlFrontMatterExtension(extractor);
     }
 

commonmark-ext-yaml-front-matter/src/main/java/org/commonmark/ext/front/matter/YamlFrontMatterExtractor.java

@@ -2,10 +2,10 @@
 
 import org.commonmark.node.CustomNode;
 
-public class YamlFrontMatterContent extends CustomNode {
+public class YamlFrontMatterRawContent extends CustomNode {
     private String content;
 
-    public YamlFrontMatterContent(String content) {
+    public YamlFrontMatterRawContent(String content) {
         this.content = content;
     }
 

…front/matter/YamlFrontMatterContent.java …nt/matter/YamlFrontMatterRawContent.javacommonmark-ext-yaml-front-matter/src/main/java/org/commonmark/ext/front/matter/YamlFrontMatterContent.java renamed to commonmark-ext-yaml-front-matter/src/main/java/org/commonmark/ext/front/matter/YamlFrontMatterRawContent.java commonmark-ext-yaml-front-matter/src/main/java/org/commonmark/ext/front/matter/YamlFrontMatterContent.java renamed to commonmark-ext-yaml-front-matter/src/main/java/org/commonmark/ext/front/matter/YamlFrontMatterRawContent.java

@@ -4,8 +4,8 @@
 import java.util.List;
 import java.util.Map;
 
-import org.commonmark.ext.front.matter.extractor.YamlDataExtractor;
-import org.commonmark.ext.front.matter.extractor.YamlContentExtractor;
+import org.commonmark.ext.front.matter.parser.YamlSubsetParser;
+import org.commonmark.ext.front.matter.parser.RawContentParser;
 import org.commonmark.node.AbstractVisitor;
 import org.commonmark.node.CustomNode;
 import org.commonmark.node.Node;
@@ -23,10 +23,10 @@ public YamlFrontMatterVisitor() {
 
     /**
      * Reads the YAML front matter metadata, if the Markdown
-     * document has the YAML front matter and the extension
-     * uses {@link YamlDataExtractor} (default).
+     * document has the front matter and the extension
+     * uses {@link YamlSubsetParser} (default).
      *
-     * @return The data stored in YAML front matter or empty map
+     * @return The data stored in YAML front matter or empty map.
      */
     public static Map<String, List<String>> readData(Node document) {
         YamlFrontMatterVisitor visitor = new YamlFrontMatterVisitor();
@@ -35,16 +35,15 @@ public static Map<String, List<String>> readData(Node document) {
     }
 
     /**
-     * Reads the YAML Front Matter metadata as a string, if the Markdown
-     * document has the YAML Front Matter and the extension uses
-     * {@link YamlContentExtractor} (default).
+     * Reads the raw content of the front matter, if the Markdown document has
+     * the front matter and the extension uses {@link RawContentParser}.
      *
-     * @return The content of YAML front matter as string or empty string.
+     * @return Raw content of the front matter as string or empty string.
      */
-    public static String readContent(Node document) {
+    public static String readRawContent(Node document) {
         YamlFrontMatterVisitor visitor = new YamlFrontMatterVisitor();
         document.accept(visitor);
-        return visitor.getContent();
+        return visitor.getRawContent();
     }
 
     @Override
@@ -55,8 +54,8 @@ public void visit(CustomNode customNode) {
                     ((YamlFrontMatterNode) customNode).getValues()
             );
             present = true;
-        } else if (customNode instanceof YamlFrontMatterContent) {
-            content = ((YamlFrontMatterContent) customNode).getContent();
+        } else if (customNode instanceof YamlFrontMatterRawContent) {
+            content = ((YamlFrontMatterRawContent) customNode).getContent();
             present = true;
         } else {
             super.visit(customNode);
@@ -65,7 +64,7 @@ public void visit(CustomNode customNode) {
 
     /**
      * Returns the YAML front matter metadata, if the Markdown document has
-     * the YAML front matter and the extension uses {@link YamlDataExtractor}
+     * the front matter and the extension uses {@link YamlSubsetParser}
      * (default).
      *
      * @return The data stored in YAML front matter or empty map
@@ -75,13 +74,13 @@ public Map<String, List<String>> getData() {
     }
 
     /**
-     * Returns the YAML Front Matter metadata as a string, if the Markdown
-     * document has the YAML Front Matter and the extension uses
-     * {@link YamlContentExtractor} (default).
+     * Returns the raw content of the front matter, if the Markdown
+     * document has the front matter and the extension uses
+     * {@link RawContentParser}.
      *
-     * @return The content of YAML front matter as string or empty string.
+     * @return Raw content of the front matter as string or empty string.
      */
-    public String getContent() {
+    public String getRawContent() {
         return content;
     }
 

commonmark-ext-yaml-front-matter/src/main/java/org/commonmark/ext/front/matter/YamlFrontMatterVisitor.java

@@ -2,21 +2,22 @@
 
 import java.util.regex.Pattern;
 
-import org.commonmark.ext.front.matter.YamlFrontMatterExtractor;
+import org.commonmark.ext.front.matter.FrontMatterParser;
 import org.commonmark.ext.front.matter.YamlFrontMatterBlock;
 import org.commonmark.node.Block;
 import org.commonmark.node.Document;
+import org.commonmark.parser.SourceLine;
 import org.commonmark.parser.block.*;
 
 public class YamlFrontMatterBlockParser extends AbstractBlockParser {
     private static final Pattern REGEX_BEGIN = Pattern.compile("^-{3}(\\s.*)?");
     private static final Pattern REGEX_END = Pattern.compile("^(-{3}|\\.{3})(\\s.*)?");
 
     private YamlFrontMatterBlock block;
-    private YamlFrontMatterExtractor extractor;
+    private FrontMatterParser frontMatterParser;
 
-    public YamlFrontMatterBlockParser(YamlFrontMatterExtractor extractor) {
-        this.extractor = extractor;
+    public YamlFrontMatterBlockParser(FrontMatterParser frontMatterParser) {
+        this.frontMatterParser = frontMatterParser;
         block = new YamlFrontMatterBlock();
     }
 
@@ -27,21 +28,26 @@ public Block getBlock() {
 
     @Override
     public BlockContinue tryContinue(ParserState parserState) {
-        final CharSequence line = parserState.getLine().getContent();
+        final SourceLine line = parserState.getLine();
 
-        if (REGEX_END.matcher(line).matches()) {
-            return extractor.onBlockEnd(block);
+        if (REGEX_END.matcher(line.getContent()).matches()) {
+            switch (frontMatterParser.onEndingSeparator(block, line)) {
+                case BLOCK_END:
+                    return BlockContinue.finished();
+                case CONTENT:
+                    return BlockContinue.atIndex(parserState.getIndex());
+            }
         }
 
-        extractor.onNextLine(block, line);
+        frontMatterParser.onNextLine(block, line);
         return BlockContinue.atIndex(parserState.getIndex());
     }
 
     public static class Factory extends AbstractBlockParserFactory {
-        private YamlFrontMatterExtractor.Factory yamlExtractorFactory;
+        private FrontMatterParser.Factory frontMatterParserFactory;
 
-        public Factory(YamlFrontMatterExtractor.Factory factory) {
-            this.yamlExtractorFactory = factory;
+        public Factory(FrontMatterParser.Factory factory) {
+            this.frontMatterParserFactory = factory;
         }
 
         @Override
@@ -52,7 +58,7 @@ public BlockStart tryStart(ParserState state, MatchedBlockParser matchedBlockPar
             if (parentParser.getBlock() instanceof Document
                     && parentParser.getBlock().getFirstChild() == null
                     && REGEX_BEGIN.matcher(line).matches()) {
-                return BlockStart.of(new YamlFrontMatterBlockParser(yamlExtractorFactory.create()))
+                return BlockStart.of(new YamlFrontMatterBlockParser(frontMatterParserFactory.create()))
                         .atIndex(state.getNextNonSpaceIndex());
             }
 

commonmark-ext-yaml-front-matter/src/main/java/org/commonmark/ext/front/matter/extractor/YamlContentExtractor.java

@@ -2,7 +2,7 @@
 
 import java.util.List;
 
-import org.commonmark.ext.front.matter.YamlFrontMatterContent;
+import org.commonmark.ext.front.matter.YamlFrontMatterRawContent;
 import org.commonmark.ext.front.matter.YamlFrontMatterNode;
 import org.commonmark.node.Node;
 import org.commonmark.renderer.markdown.MarkdownNodeRendererContext;
@@ -22,8 +22,8 @@ public void render(Node node) {
         while (child != null) {
             if (child instanceof YamlFrontMatterNode) {
                 renderNode((YamlFrontMatterNode) child);
-            } else if (child instanceof YamlFrontMatterContent) {
-                renderContent((YamlFrontMatterContent) child);
+            } else if (child instanceof YamlFrontMatterRawContent) {
+                renderContent((YamlFrontMatterRawContent) child);
             }
             child = child.getNext();
         }
@@ -117,7 +117,7 @@ private boolean isFlowCollection(String value) {
                 || (value.startsWith("{") && value.endsWith("}"));
     }
 
-    private void renderContent(YamlFrontMatterContent content) {
+    private void renderContent(YamlFrontMatterRawContent content) {
         String body = content.getContent();
         writer.raw(body);
         if (!body.endsWith("\n")) {