Package com.puppycrawl.tools.checkstyle.site

Class TocMacro

java.lang.Object
org.apache.maven.doxia.macro.AbstractMacro
com.puppycrawl.tools.checkstyle.site.TocMacro
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="sitetoc") public class TocMacro extends org.apache.maven.doxia.macro.AbstractMacro
A macro that generates an "In this article" table of contents for an xdoc page. Every canonical section key in SECTION_NAMES is attempted for every page; the anchor id used in the link is read directly from a matching <subsection> tag's real id attribute, so links can never drift from what the page actually renders, and any section not present in a given file's source is silently skipped -- pages do not need to declare which sections they have. Examples and Use Cases subsections additionally get nested entries, titled either by the first non-default property=value found in the example's referenced source file, or by a shortened form of the example's descriptive paragraph when no distinguishing property can be found.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final record 
    TocMacro.TocContext
    Bundles the per-page context needed while writing TOC entries, so helper methods don't need long parameter lists.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final String
    DEFAULT_TITLE
    Fallback title when no descriptive paragraph is available.
    private static final String
    EXAMPLES_BASE_DIR
    Base directory that example path params are resolved against.
    private static final int
    GROUP_EXAMPLE_PATH
    Regex group index of the path param's value in ITEM_WITH_PATH_PATTERN.
    private static final int
    GROUP_ID_ID_FIRST
    Regex group index of the id attribute when it appears first (id, name order).
    private static final int
    GROUP_ID_NAME_FIRST
    Regex group index of the id attribute when it appears second (name, id order).
    private static final int
    GROUP_NAME_ID_FIRST
    Regex group index of the name attribute when it appears second (id, name order).
    private static final Pattern
    ITEM_WITH_PATH_PATTERN
    Matches an Example/UseCase paragraph followed immediately by its example macro.
    private static final Pattern
    LEAD_IN_PATTERN
    Strips the common "To configure the check to produce a violation on/when" lead-in.
    private static final String
    LI_CLOSE
    Closing anchor/list-item tag pair used to end a TOC entry.
    private static final Set<String>
    NESTED_SECTIONS
    Section keys that get nested sub-entries.
    private static final Pattern
    PROPERTY_PATTERN
    Matches a property assignment inside an example's embedded config comment.
    private static final String
    QUOTE
    A single double quote character, used to open HTML attribute values.
    private static final String
    QUOTE_CLOSE_TAG
    Closing quote and angle bracket used when terminating an HTML attribute.
    private static final String
    SECTION_DESCRIPTION
    Section key/name: Description.
    private static final String
    SECTION_EXAMPLES
    Section key/name: Examples.
    private static final Map<String,String>
    SECTION_NAMES
    Maps every canonical section key, in the fixed order TOC entries should appear, to the subsection's name attribute value.
    private static final String
    SECTION_PROPERTIES
    Section key/name: Properties.
    private static final String
    SECTION_USE_CASES_KEY
    Section key: UseCases.
    private static final Pattern
    SUBSECTION_TAG_PATTERN
    Matches a subsection tag and captures its name/id attributes, in either order.
    private static final Pattern
    TAG_PATTERN
    Strips inline HTML tags left in scraped paragraph text except <code> tags.
    private static final String
    TOKENS_PROPERTY
    Property name to always skip when deriving a property=value title.
    private static final Pattern
    WHITESPACE_PATTERN
    Collapses any run of whitespace (including newlines) into a single space.

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

    EOL, ROLE

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    private static Optional<String>
    derivePropertyTitle(String examplePath, TocMacro.TocContext context)
    Reads an example's referenced source file and finds the first property whose value differs from its documented default, skipping tokens.
    void
    execute(org.apache.maven.doxia.sink.Sink sink, org.apache.maven.doxia.macro.MacroRequest request)
     
    private static Optional<String>
    extractPropertyTitle(Matcher propMatcher, Map<String,PropertyDetails> propertyDetails)
    Extracts a property title from a matcher group if the property differs from its default value.
    private static String
    extractSectionBody(String sourceContent, String anchorId)
    Extracts the text of one subsection from the full source, bounded by that subsection's opening tag and the next subsection's opening tag.
    private static Optional<String>
    findSubsectionAnchor(String sourceContent, String sectionName)
    Finds the actual id attribute value of the <subsection> tag whose name attribute matches the given section name.
    private static Map<String,PropertyDetails>
    loadPropertyDetails(String modulePath)
    Loads documented property defaults for the current module, if a modulePath param was supplied.
    private static String
    normalizeWhitespace(String text)
    Collapses internal newlines/indentation from raw xdoc paragraph text into single spaces, so tooltips and labels render on one line.
    private static Path
    resolveRepoRoot(String modulePath)
    Derives the repository root from the module's source path so example resource paths (relative to EXAMPLES_BASE_DIR) can be resolved to an absolute file location.
    private static String
    toSentenceTitle(String rawParagraph)
    Converts a raw "ExampleN-config"/"UseCaseN-config" paragraph into a short sentence-based title by removing inline markup, normalizing whitespace, stripping the common lead-in clause, and trimming the trailing colon.
    private static void
    writeNestedItems(org.apache.maven.doxia.sink.Sink sink, String sectionBody, TocMacro.TocContext context)
    Writes nested <li> entries for each Example/UseCase found within a subsection's body text, titled by property=value when possible, falling back to a shortened descriptive sentence.
    private static void
    writeSectionEntry(org.apache.maven.doxia.sink.Sink sink, String section, TocMacro.TocContext context)
    Writes a single top-level <li>, with nested Example/UseCase entries when the section is Examples or Use Cases.

    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

    • TocMacro

      public TocMacro()
      Creates a new TocMacro instance.

  • Method Details

    • execute

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

    • writeSectionEntry

      private static void writeSectionEntry(org.apache.maven.doxia.sink.Sink sink, String section, TocMacro.TocContext context)
      Writes a single top-level <li>, with nested Example/UseCase entries when the section is Examples or Use Cases. The anchor id is read directly from the matching <subsection> tag's actual id attribute in the source, rather than assumed from a naming convention, so the link can never drift from what the page really renders. If no matching <subsection> exists in the source, nothing is written for this section -- pages are not required to have every canonical section.
      Parameters:
      sink - sink to write to.
      section - the canonical section key.
      context - shared per-page context for resolving anchors and titles.

    • findSubsectionAnchor

      private static Optional<String> findSubsectionAnchor(String sourceContent, String sectionName)
      Finds the actual id attribute value of the <subsection> tag whose name attribute matches the given section name.
      Parameters:
      sourceContent - the full template source text.
      sectionName - the subsection's name attribute value to match.
      Returns:
      the subsection's real id, or empty if no matching tag is found.

    • extractSectionBody

      private static String extractSectionBody(String sourceContent, String anchorId)
      Extracts the text of one subsection from the full source, bounded by that subsection's opening tag and the next subsection's opening tag.
      Parameters:
      sourceContent - the full template source text.
      anchorId - the subsection's id attribute value.
      Returns:
      the subsection's raw inner text, or an empty string if not found.

    • writeNestedItems

      private static void writeNestedItems(org.apache.maven.doxia.sink.Sink sink, String sectionBody, TocMacro.TocContext context)
      Writes nested <li> entries for each Example/UseCase found within a subsection's body text, titled by property=value when possible, falling back to a shortened descriptive sentence. Titles are shown in full and allowed to wrap across lines, rather than being truncated with an ellipsis, so the whole label is always readable.
      Parameters:
      sink - sink to write to.
      sectionBody - the raw text of the subsection.
      context - shared per-page context for resolving titles.

    • loadPropertyDetails

      private static Map<String,PropertyDetails> loadPropertyDetails(String modulePath)
      Loads documented property defaults for the current module, if a modulePath param was supplied. Returns an empty map otherwise, or if lookup fails for any reason -- property-based titling is a nice-to-have, not something that should break page generation.
      Parameters:
      modulePath - path to the module's Java source, or null.
      Returns:
      a map of property name to its documented details.

    • resolveRepoRoot

      private static Path resolveRepoRoot(String modulePath)
      Derives the repository root from the module's source path so example resource paths (relative to EXAMPLES_BASE_DIR) can be resolved to an absolute file location.
      Parameters:
      modulePath - path to the module's Java source, or null.
      Returns:
      the repository root, or the current working directory if modulePath is absent or doesn't contain the expected marker.

    • derivePropertyTitle

      private static Optional<String> derivePropertyTitle(String examplePath, TocMacro.TocContext context)
      Reads an example's referenced source file and finds the first property whose value differs from its documented default, skipping tokens.
      Parameters:
      examplePath - the path param value from the example macro.
      context - shared per-page context providing property defaults and repo root.
      Returns:
      an "name=value" title, or empty if the file can't be read or every property in it matches its documented default.

    • extractPropertyTitle

      private static Optional<String> extractPropertyTitle(Matcher propMatcher, Map<String,PropertyDetails> propertyDetails)
      Extracts a property title from a matcher group if the property differs from its default value.
      Parameters:
      propMatcher - the property matcher positioned at a match.
      propertyDetails - the documented property defaults.
      Returns:
      an "name=value" title, or empty if the property matches default.

    • toSentenceTitle

      private static String toSentenceTitle(String rawParagraph)
      Converts a raw "ExampleN-config"/"UseCaseN-config" paragraph into a short sentence-based title by removing inline markup, normalizing whitespace, stripping the common lead-in clause, and trimming the trailing colon. Used as a fallback when no distinguishing property can be found.
      Parameters:
      rawParagraph - the paragraph's raw inner text.
      Returns:
      a short, human-readable title.

    • normalizeWhitespace

      private static String normalizeWhitespace(String text)
      Collapses internal newlines/indentation from raw xdoc paragraph text into single spaces, so tooltips and labels render on one line.
      Parameters:
      text - the raw text, possibly containing multi-line whitespace.
      Returns:
      the text with all whitespace runs collapsed to a single space.