Package com.puppycrawl.tools.checkstyle.site

Class ExampleMacro

java.lang.Object
org.apache.maven.doxia.macro.AbstractMacro
com.puppycrawl.tools.checkstyle.site.ExampleMacro
All Implemented Interfaces:
org.apache.maven.doxia.logging.LogEnabled, org.apache.maven.doxia.macro.Macro
@Component(role=org.apache.maven.doxia.macro.Macro.class, hint="example") public class ExampleMacro extends org.apache.maven.doxia.macro.AbstractMacro
A macro that inserts a snippet of code or configuration from a file.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final String
    CODE_SNIPPET_END
    Ending delimiter for code snippets.
    private static final String
    CODE_SNIPPET_START
    Starting delimiter for code snippets.
    private static final String
    LANGUAGE_XML
    The prettyprint language class for XML content.
    private List<String>
    lastLines
    The line contents of the last file.
    private String
    lastPath
    The path of the last file.
    private static final String
    PROPERTIES_EXTENSION
    File extension for .properties files.

    Fields inherited from interface org.apache.maven.doxia.macro.Macro

    EOL, ROLE

  • Constructor Summary

    Constructors
    Constructor
    Description
    ExampleMacro()
    Creates a new ExampleMacro instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    private static String
    determineLanguageClass(String extension, boolean isConfig)
    Determines the prettyprint language class to use for a snippet, based on the source file's extension.
    private static String
    escapeHtml(String snippet)
    Escapes HTML special characters in the snippet.
    void
    execute(org.apache.maven.doxia.sink.Sink sink, org.apache.maven.doxia.macro.MacroRequest request)
     
    private static String
    getCodeSnippet(Collection<String> lines)
    Extract a code snippet from the given lines.
    private static String
    getConfigSnippet(Collection<String> lines, String extension)
    Extracts the configuration snippet from the given lines.
    private static String
    getExtension(String path)
    Extracts the file extension (including the leading dot) from a file path, or an empty string if the path has no extension.
    private static boolean
    hasCodeSnippetEnd(String line)
    Checks if the line contains a code snippet end delimiter.
    private static boolean
    hasCodeSnippetStart(String line)
    Checks if the line contains a code snippet start delimiter.
    private static List<String>
    readFile(String path)
    Read the file at the given path and returns its contents as a list of lines.
    private static void
    writeCodeSnippet(org.apache.maven.doxia.sink.Sink sink, List<String> lines, String path)
    Extracts the code snippet from the given lines and writes it to the sink.
    private static void
    writeConfigSnippet(org.apache.maven.doxia.sink.Sink sink, List<String> lines, String path)
    Extracts the config snippet from the given lines and writes it to the sink.
    private static void
    writeSnippet(org.apache.maven.doxia.sink.Sink sink, String snippet, String extension, boolean isConfig)
    Writes the given snippet inside a formatted source block, choosing syntax highlighting based on the source file's extension.

    Methods inherited from class org.apache.maven.doxia.macro.AbstractMacro

    enableLogging, getAttributesFromMap, getLog, required

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • ExampleMacro

      public ExampleMacro()
      Creates a new ExampleMacro instance.

  • Method Details

    • execute

      public void execute(org.apache.maven.doxia.sink.Sink sink, org.apache.maven.doxia.macro.MacroRequest request) throws org.apache.maven.doxia.macro.MacroExecutionException
      Throws:
      org.apache.maven.doxia.macro.MacroExecutionException

    • writeConfigSnippet

      private static void writeConfigSnippet(org.apache.maven.doxia.sink.Sink sink, List<String> lines, String path) throws org.apache.maven.doxia.macro.MacroExecutionException
      Extracts the config snippet from the given lines and writes it to the sink.
      Parameters:
      sink - the sink to write to.
      lines - the lines of the source file.
      path - the file path, used for extension detection and error messages.
      Throws:
      org.apache.maven.doxia.macro.MacroExecutionException - if the config block is invalid or empty.

    • writeCodeSnippet

      private static void writeCodeSnippet(org.apache.maven.doxia.sink.Sink sink, List<String> lines, String path) throws org.apache.maven.doxia.macro.MacroExecutionException
      Extracts the code snippet from the given lines and writes it to the sink.
      Parameters:
      sink - the sink to write to.
      lines - the lines of the source file.
      path - the file path, used for tab-replacement detection and error messages.
      Throws:
      org.apache.maven.doxia.macro.MacroExecutionException - if the code snippet is empty.

    • readFile

      private static List<String> readFile(String path) throws org.apache.maven.doxia.macro.MacroExecutionException
      Read the file at the given path and returns its contents as a list of lines.
      Parameters:
      path - the path to the file to read.
      Returns:
      the contents of the file as a list of lines.
      Throws:
      org.apache.maven.doxia.macro.MacroExecutionException - if the file could not be read.

    • getExtension

      private static String getExtension(String path)
      Extracts the file extension (including the leading dot) from a file path, or an empty string if the path has no extension.
      Parameters:
      path - the file path.
      Returns:
      the file extension, e.g. ".xml", or "" if none.

    • getConfigSnippet

      private static String getConfigSnippet(Collection<String> lines, String extension)
      Extracts the configuration snippet from the given lines.
      Parameters:
      lines - the lines to extract the config from.
      extension - the file extension (e.g. ".xml"), used to decide which delimiter conventions are valid.
      Returns:
      the configuration snippet.
      Throws:
      IllegalArgumentException - if the config block is invalid.

    • getCodeSnippet

      private static String getCodeSnippet(Collection<String> lines)
      Extract a code snippet from the given lines. Code delimiters can be indented, so we use contains() instead of equals(). If the delimiters are not found, returns the file content excluding the XML config block (if present).
      Parameters:
      lines - the lines to extract the snippet from.
      Returns:
      the code snippet.

    • hasCodeSnippetStart

      private static boolean hasCodeSnippetStart(String line)
      Checks if the line contains a code snippet start delimiter.
      Parameters:
      line - the line to check.
      Returns:
      true if the line contains a start delimiter.

    • hasCodeSnippetEnd

      private static boolean hasCodeSnippetEnd(String line)
      Checks if the line contains a code snippet end delimiter.
      Parameters:
      line - the line to check.
      Returns:
      true if the line contains an end delimiter.

    • writeSnippet

      private static void writeSnippet(org.apache.maven.doxia.sink.Sink sink, String snippet, String extension, boolean isConfig)
      Writes the given snippet inside a formatted source block, choosing syntax highlighting based on the source file's extension. Config snippets (the content inside a Java-comment-style config block) are always XML regardless of the target file's extension, except for .properties files, whose bare #-comment config block is not highlighted at all.
      Parameters:
      sink - the sink to write to.
      snippet - the snippet to write.
      extension - the source file extension, e.g. ".xml", ".sql".
      isConfig - true if the snippet is a config block rather than a code block.

    • determineLanguageClass

      private static String determineLanguageClass(String extension, boolean isConfig)
      Determines the prettyprint language class to use for a snippet, based on the source file's extension.
      Parameters:
      extension - the source file extension, e.g. ".xml", ".sql".
      isConfig - true if the snippet is a config block (always XML syntax, except for .properties files.
      Returns:
      the language class to apply, or null if the snippet should not be syntax-highlighted.

    • escapeHtml

      private static String escapeHtml(String snippet)
      Escapes HTML special characters in the snippet.
      Parameters:
      snippet - the snippet to escape.
      Returns:
      the escaped snippet.