Class IndentationCalculator

java.lang.Object
com.github.javaparser.printer.lexicalpreservation.IndentationCalculator
public final class IndentationCalculator extends 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:

  • Method Details

    • computeFromPrecedingElements

      public static List<TextElement> computeFromPrecedingElements(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 List<TextElement> extractIndentationFromTokens(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 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