gudusoft.gsqlparser.pp2.region

Class RegionParseOutcome

Object

gudusoft.gsqlparser.pp2.region.RegionParseOutcome

public final class RegionParseOutcome
extends Object

Immutable per-region outcome produced by ParseRecoveryEngine.

The outcome carries one of three statuses:

• RegionParseOutcome.Status.AST_OK — the region's source slice parsed cleanly. getStatement() returns the AST root captured from the parser. The getSyntaxErrors() list is empty.
• RegionParseOutcome.Status.AST_ERROR — parse failed (or was skipped by the maxRegionParseChars safety valve, or the parser threw). getStatement() is null. getSyntaxErrors() carries the parser's diagnostics (possibly empty if the engine could not capture them — e.g., after a Throwable). The optional getEngineNote() field carries a short message describing why this region was marked AST_ERROR when the parser itself did not report a diagnostic (e.g., region too large, parser threw).
• RegionParseOutcome.Status.TRIVIA — the region contains no solid tokens (only whitespace and / or comments). No parse was attempted. getStatement() is null, getSyntaxErrors() is empty.

AST lifetime contract. Every AST_OK outcome carries a reference to the TGSqlParser that produced it. That parser owns the captured AST (statement tree, source-token list, error list) and is the input S13 (GuardedAstDelegate) and S16 (Pp2Engine) hand to FormatterFactory.pp(parser, opt) via getParser(). Two scenarios:

• parseRegion: the parser is the pool's single instance. Its state is overwritten on the next parseRegion / parseAll call. Consume the AST before requesting the next region.
• parseAll: every AST_OK outcome carries a freshly-allocated parser dedicated to that region (the engine probes each range via the pool, and on success re-parses the slice into a new TGSqlParser so parser.sqlstatements holds exactly one statement). Outcomes are mutually valid: a caller may iterate the returned list in any order and consume each AST without invalidating the rest. The contract is broken by the next parseAll / parseRegion call on the same engine only for outcomes produced via parseRegion (which share the pool); parseAll's dedicated parsers outlive the engine call.

Plan reference: §7.3/S12, §7.4/S12.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RegionParseOutcome.Status

Method Summary

Modifier and Type	Method and Description
static RegionParseOutcome	astError(StatementRange range, String parsedSql, List<TSyntaxError> errors, String note) Build an AST_ERROR outcome.
String	getEngineNote() Short engine-level note explaining the outcome when the parser itself did not report a diagnostic.
String	getParsedSql() The source text that was (or would have been) handed to the parser.
TGSqlParser	getParser() The TGSqlParser that produced the AST for this outcome.
StatementRange	getRange()
TCustomSqlStatement	getStatement() The captured AST root for AST_OK outcomes; null otherwise.
RegionParseOutcome.Status	getStatus()
List<TSyntaxError>	getSyntaxErrors() Immutable list of syntax errors.
String	toString()
static RegionParseOutcome	trivia(StatementRange range, String parsedSql) Build a TRIVIA outcome (region with no solid tokens — only whitespace and/or comments).

Methods inherited from class Object

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

Method Detail

astError

public static RegionParseOutcome astError(StatementRange range,
                                          String parsedSql,
                                          List<TSyntaxError> errors,
                                          String note)

Build an AST_ERROR outcome. Used by the engine for parse failures and safety-valve skips; also useful to tests and downstream stages that need to package a synthetic error outcome (e.g., a region the boundary detector emitted but parsing was bypassed).

errors may be null or empty.

trivia

public static RegionParseOutcome trivia(StatementRange range,
                                        String parsedSql)

Build a TRIVIA outcome (region with no solid tokens — only whitespace and/or comments).

getRange

public StatementRange getRange()

getStatus

public RegionParseOutcome.Status getStatus()

getParsedSql

public String getParsedSql()

The source text that was (or would have been) handed to the parser.

getStatement

public TCustomSqlStatement getStatement()

The captured AST root for AST_OK outcomes; null otherwise. See the class Javadoc for the AST lifetime contract.

getParser

public TGSqlParser getParser()

The TGSqlParser that produced the AST for this outcome. Non-null only when getStatus() is RegionParseOutcome.Status.AST_OK; null otherwise. See the class Javadoc for the lifetime contract; in particular, after the next ParseRecoveryEngine.parseRegion(StatementRange) or ParseRecoveryEngine.parseAll(List) call the parser handed back here may have been overwritten in place (for outcomes produced via the pool) and must not be reused.

getSyntaxErrors

public List<TSyntaxError> getSyntaxErrors()

Immutable list of syntax errors. Empty for AST_OK and TRIVIA.

getEngineNote

public String getEngineNote()

Short engine-level note explaining the outcome when the parser itself did not report a diagnostic. Examples: "region exceeds maxRegionParseChars", "parser threw: NullPointerException". null when not applicable.

toString

public String toString()

Overrides:

toString in class Object