Regex Rules Based Automation - sgml/signature GitHub Wiki

header: >
  LiterateDocletGeneratorWithRegexYaml (Java 25+ Edition)
  ---------------------------------------------------------
  This program demonstrates two core features:
    • It extracts Javadoc-style doclet comments using a regex.
    • The regex is structured with YAML-like indentation and inline commentary
      (with extended regex mode enabled) to explain each metacharacter.
    • All output is logged to a file named "foo.txt" using the Java Logging API.
  
code: |
  /*
   * LiterateDocletGeneratorWithRegexYaml
   * --------------------------------------
   * This program extracts doclet comments from a source string using a regex
   * written in extended mode. The regex is formatted with YAML-style indentation,
   * making it easy to understand each part of the expression. The program logs all
   * output to "foo.txt" instead of printing to the console.
   */

  import java.util.regex.Pattern;
  import java.util.regex.Matcher;
  import java.util.ArrayList;
  import java.util.List;
  import java.util.logging.Logger;
  import java.util.logging.FileHandler;
  import java.util.logging.SimpleFormatter;
  import java.io.IOException;

  // A record representing the content of an extracted doclet comment.
  public record DocletData(String content) {}

  // Main class demonstrating the extraction and logging of doclet comments.
  public class LiterateDocletGeneratorWithRegexYaml {

      // Configure a Logger to write output to "foo.txt".
      private static final Logger LOGGER = Logger.getLogger(LiterateDocletGeneratorWithRegexYaml.class.getName());
      static {
          try {
              var fileHandler = new FileHandler("foo.txt");
              fileHandler.setFormatter(new SimpleFormatter());
              LOGGER.addHandler(fileHandler);
              LOGGER.setUseParentHandlers(false); // Disable console logging.
          } catch (IOException | SecurityException e) {
              e.printStackTrace();
          }
      }

      /**
       * Extracts Javadoc-style doclet comments from a source string using a regex with YAML-like indentation.
       *
       * The regex pattern below (with extended mode enabled) is structured as follows:
       *
       *   (?x)                                    # Enable extended mode: whitespace is ignored, comments allowed.
       *   \/\\*\\*                                # Match literal '/**'
       *     (                                     # Start capture group 1 for the doclet's inner content.
       *       .*?                                 # Lazily match any character (DOTALL: '.' matches newline characters).
       *     )                                     # End capture group 1.
       *   \\*\/                                   # Match literal '*/'
       *
       * With the DOTALL flag, the '.' matches newline characters, ensuring multi-line doclets are captured.
       *
       * @param source The source code containing potential doclet comments.
       * @return A list of DocletData records with each doclet's inner content.
       */
      public static List<DocletData> extractDoclets(String source) {
          var regex = """
              (?x)                                    # Enable extended mode.
              /\\*\\*                                 # Match literal '/**'
                (                                    # Start capture group 1 for doclet content.
                  .*?                                # Lazily match any character (DOTALL mode enabled).
                )                                    # End capture group 1.
              \\*/                                   # Match literal '*/'
              """;

          // Compile the regex with the DOTALL flag so '.' matches newline characters.
          var pattern = Pattern.compile(regex, Pattern.DOTALL);
          var matcher = pattern.matcher(source);
          var doclets = new ArrayList<DocletData>();

          // Iterate over matches and add the trimmed doclet content to the list.
          while (matcher.find()) {
              var content = matcher.group(1).strip();
              doclets.add(new DocletData(content));
          }
          return doclets;
      }

      /**
       * Main method demonstrating:
       *   1. Defining a sample source with a Javadoc doclet.
       *   2. Extracting the doclet content using the YAML-indented regex.
       *   3. Logging the extracted information to "foo.txt".
       */
      public static void main(String[] args) {
          var source = """
              /** @tag DemoDoclet
               * This doclet demonstrates extraction using a regex with YAML-like indentation.
               * All messages are logged to 'foo.txt' using java.util.logging.
               */
              public class Demo {}
              """;

          var doclets = extractDoclets(source);
          LOGGER.info("Extracted Doclets:");
          for (var doclet : doclets) {
              LOGGER.info("Doclet Content:");
              LOGGER.info(doclet.content());
              LOGGER.info("-----");
          }
      }
  }

footer: >
  Final Remarks:
  --------------
  This YAML structure embeds the entire Java program as a code block.
  The header provides context and instructions, while the footer supplies closing
  remarks and summaries. This design demonstrates how to nest code and its commentary
  inside a YAML document, easily separating documentation from implementation.