gudusoft.gsqlparser.pp2.engine

Class Pp2Engine

Object

gudusoft.gsqlparser.pp2.engine.Pp2Engine

public final class Pp2Engine
extends Object

Fault-tolerant SQL formatter engine — Phase-2 MVP orchestrator.

Whole-document fast path (tried first)

Before any of the stages below, and unless Pp2FormatOptions.wholeDocumentFastPath is switched off, the engine parses the whole input and — if that succeeds — formats it with FormatterFactory.pp, returning pp's output unchanged once it passes the TokenEquivalence guard. So for SQL that parses, pp2 is a call to pp plus a guard; the regional pipeline below exists for the input pp cannot handle. See wholeDocumentFastPath(String, EDbVendor, Pp2FormatOptions).

Pipeline summary (regional path)

When the fast path does not apply, each format(String, EDbVendor, Pp2FormatOptions) call runs the following stages in order:

1. Tokenize — TGSqlParser.tokenizeSqltext() produces a raw TSourceTokenList.
2. Token spine — Pp2TokenStreamBuilder adapts the token list into a Pp2TokenStream: folds whitespace into precedingBlanks / precedingLinebreaks counts, preserves comments as first-class tokens.
3. Ledger — SourceSpanLedger records every byte of the original input so the assembler can restore inter-region trivia verbatim.
4. Zone annotation — ProtectedZoneDetector annotates NO_FORMAT_ZONE, COMMENT_LINE, COMMENT_BLOCK, and template-placeholder roles onto the token stream.
5. Boundary detection — StatementBoundaryDetector walks the annotated stream and emits one StatementRange per statement.
6. Parse recovery — ParseRecoveryEngine.parseAll(List) attempts per-region parsing. Each outcome is tagged AST_OK | AST_ERROR | TRIVIA.
7. Dispatch — EngineDispatch routes each outcome to the appropriate renderer (plan §5.2 three-tier strategy): AST_OK → GuardedAstDelegate, which formats that region with FormatterFactory.pp as well (falling through on guard failure); AST_ERROR → LexicalIslandRenderer, then ConservativeTokenRenderer; TRIVIA → passthrough. Each rendered text is wrapped in a RenderedRegion.
8. Assembly — RegionAssembler interleaves the rendered texts with the original inter-region trivia from the ledger, producing the final output string.
9. Result — a Pp2FormatResult carrying the assembled text, FormatStatus, per-region Pp2FormatResult.Region records, and all diagnostics accumulated across the pipeline.

Defensive behaviour

The engine never throws for non-null inputs. Any Throwable that escapes the pipeline — from the tokenizer, ledger builder, boundary detector, or assembler — is caught, logged via PPLogger, and the engine falls back to returning the original SQL unchanged with FormatStatus.FAILED and a FormatDiagnostic.Severity#FATAL diagnostic.

Thread safety

The engine instance is stateless (all mutable objects are allocated per format call). Concurrent calls with different inputs are safe. The inner ParseRecoveryEngine allocates a fresh ParserPool per call.

Plan reference: §5.1, §7.3/S16, §7.4/S16, §10.4.

Constructor Summary

Constructors

Constructor and Description
Pp2Engine()

Method Summary

Modifier and Type	Method and Description
Pp2FormatResult	format(String sql, EDbVendor vendor, Pp2FormatOptions opts) Format the given SQL string using the supplied database vendor and options.

Methods inherited from class Object

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

Constructor Detail

Pp2Engine

public Pp2Engine()

Method Detail

format

public Pp2FormatResult format(String sql,
                              EDbVendor vendor,
                              Pp2FormatOptions opts)

Format the given SQL string using the supplied database vendor and options. Never throws for non-null inputs.

Parameters:

sql - the raw SQL to format; must not be null

vendor - the database dialect; governs tokenization, keyword recognition, and boundary detection

opts - formatting options; must not be null

Returns:

a Pp2FormatResult carrying the formatted text and per-region metadata; never null

Throws:

NullPointerException - if any argument is null