Package com.github.javaparser.printer.lexicalpreservation

Class IndentationCalculator

  • public final class IndentationCalculator
extends java.lang.Object
    Provides stateless utility methods for indentation calculations and analysis. This class contains pure functions that compute indentation-related values without maintaining any state. All methods are static and can be used independently without creating an instance. Typical operations include: - Computing indentation from preceding elements - Analyzing indentation context for enforcement - Creating standard indentation blocks - Extracting indentation from token sequences
    See Also:
    for stateful indentation management

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static IndentationCalculator.EnforcingContext analyzeEnforcingContext​(com.github.javaparser.printer.lexicalpreservation.NodeText nodeText, int index)
      Analyzes the indentation enforcement context at a given position in the node text.
      static java.util.List<TextElement> computeFromPrecedingElements​(java.util.List<TextElement> precedingElements)
      Computes the indentation that should be used based on the elements preceding the current position.
      static java.util.List<TextElement> createIndentationBlock()
      Creates a single indentation block of STANDARD_INDENTATION_SIZE spaces.
      static int enforceIndentation​(com.github.javaparser.printer.lexicalpreservation.NodeText nodeText, int index, int charactersToPreserve)
      Applies indentation enforcement at the specified position, preserving the specified number of characters.
      static java.util.List<TextElement> extractIndentationFromTokens​(java.util.List<TextElement> precedingTokens)
      Extracts the indentation portion from a list of elements.
      static int removeExcessIndentation​(com.github.javaparser.printer.lexicalpreservation.NodeText nodeText, int startIndex, int count)
      Removes excess indentation characters from the node text.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • computeFromPrecedingElements

        public static java.util.List<TextElement> computeFromPrecedingElements​(java.util.List<TextElement> precedingElements)
        Computes the indentation that should be used based on the elements preceding the current position. This analyzes the elements to find the last newline and extracts all whitespace characters that follow it. This method is used when we need to match existing indentation in the source code.
        Parameters:
        precedingElements - elements before the current position
        Returns:
        list of indentation elements (spaces/tabs) after the last newline, or empty list if no newline found

      • extractIndentationFromTokens

        public static java.util.List<TextElement> extractIndentationFromTokens​(java.util.List<TextElement> precedingTokens)
        Extracts the indentation portion from a list of elements. This method differs from computeFromPrecedingElements because it doesn't look for a newline first - it assumes the list represents tokens after a newline and simply extracts all leading whitespace. This is useful when we have already collected preceding tokens and want to extract just the indentation part.
        Parameters:
        precedingTokens - tokens that precede the position
        Returns:
        list of indentation elements (leading whitespace only)

      • createIndentationBlock

        public static java.util.List<TextElement> createIndentationBlock()
        Creates a single indentation block of STANDARD_INDENTATION_SIZE spaces. This is used when we need to add one level of indentation temporarily.
        Returns:
        list containing STANDARD_INDENTATION_SIZE space elements

      • analyzeEnforcingContext

        public static IndentationCalculator.EnforcingContext analyzeEnforcingContext​(com.github.javaparser.printer.lexicalpreservation.NodeText nodeText,
                                                                             int index)
        Analyzes the indentation enforcement context at a given position in the node text.

        Context and Purpose:

        This method is primarily used by the Difference class during AST modification to determine if excess whitespace should be removed after deleting elements. When a node is removed from the AST, surrounding whitespace may need to be adjusted to maintain proper formatting.

        Algorithm Overview:

        The algorithm performs a two-phase scan to identify excess whitespace:
        1. Backward Scan: Looks backward from the given index to find contiguous whitespace characters, stopping at either a newline or a non-whitespace element.
        2. Forward Scan: If the current position contains whitespace, scans forward to count additional contiguous whitespace characters.

        Examples:

         Example 1 - Whitespace between elements after deletion:
   Before: "public class A { int foo; }"
   After deletion of "int foo;": "public class A { [space][space] }"
   analyzeEnforcingContext(nodeText, firstSpaceIndex) returns:
     - startIndex: index of first space
     - extraCharacters: 2 (both spaces should be considered for removal)

 Example 2 - Indentation after newline:
   Structure: "[newline][space][space][space][space]public"
   analyzeEnforcingContext(nodeText, middleSpaceIndex) returns:
     - startIndex: index of first space after newline
     - extraCharacters: 4 (all indentation spaces)

 Example 3 - Non-whitespace interrupts sequence:
   Structure: "public[space][space]"
   analyzeEnforcingContext(nodeText, firstSpaceIndex) returns:
     - startIndex: index of first space (reset due to "public")
     - extraCharacters: 2 (spaces after "public")

        Important Behavior:

        When a non-whitespace element is encountered during the backward scan, the context is reset (start becomes the current index, extraCharacters becomes 0), but the forward scan still executes if the current position is whitespace. This allows the method to identify and count trailing spaces after non-whitespace elements.
        Parameters:
        nodeText - the node text being modified
        index - position to analyze (typically points to a position after a deletion)
        Returns:
        context containing the start index and count of excess whitespace characters

      • removeExcessIndentation

        public static int removeExcessIndentation​(com.github.javaparser.printer.lexicalpreservation.NodeText nodeText,
                                          int startIndex,
                                          int count)
        Removes excess indentation characters from the node text. This method modifies the provided NodeText by removing a specified number of elements starting from the given index.
        Parameters:
        nodeText - the node text to modify
        startIndex - where to start removing
        count - how many characters to remove
        Returns:
        the new index position after removal

      • enforceIndentation

        public static int enforceIndentation​(com.github.javaparser.printer.lexicalpreservation.NodeText nodeText,
                                     int index,
                                     int charactersToPreserve)
        Applies indentation enforcement at the specified position, preserving the specified number of characters. This is the main enforcement method that: 1. Analyzes the context to determine extra whitespace 2. Calculates how much to remove based on charactersToPreserve 3. Removes the excess 4. Returns the adjusted index
        Parameters:
        nodeText - the node text to modify
        index - current position
        charactersToPreserve - how many indentation characters to keep
        Returns:
        the new index position after enforcement