gudusoft.gsqlparser.pp2.render

Interface RegionRenderer

All Known Implementing Classes:

ConservativeTokenRenderer, GuardedAstDelegate, LexicalIslandRenderer

public interface RegionRenderer

Strategy interface for rendering a single RegionParseOutcome to its final text. Implementations are dispatched by gudusoft.gsqlparser.pp2.engine.Pp2Engine (S16) and form the three-tier renderer pipeline of plan §5.2:

• GuardedAstDelegate (S13) — wraps FormatterFactory.pp(parser, opt) and runs a TokenEquivalence guard on the output. Used when the engine has an AST for the region.
• ConservativeTokenRenderer (S14, Phase-2 MVP) — emits tokens with light spacing. The minimum-viable last-resort that guarantees content preservation.
• LexicalIslandRenderer (S31, Phase-3 quality) — full Java port of the Delphi TSQLion pipeline. Replaces the conservative renderer for AST_ERROR regions once Phase 3 ships; conservative remains as the last-resort safety net.

Fall-through contract

Implementations must not throw for any valid, non-null inputs. Argument-validity assertions (NullPointerException on null outcome / opts) are the only exceptions allowed — they signal a caller bug, not a recoverable rendering failure. On any recoverable failure (parser exception, guard violation, internal renderer error) the implementation must return null so the engine can route the region to the next renderer in the chain.

null is the only fall-through sentinel. An empty String ("") is a valid rendering of a legitimately empty region (trivia at end-of-input, an explicitly-empty user fragment) and must not be re-interpreted as a fall-through by the engine.

Diagnostic messages should be emitted via PPLogger; structured FormatDiagnostic entries are attached by the engine (S16), not the renderer.

Plan reference: §5.2, §7.3/S13, §10.2.

Method Summary

Modifier and Type	Method and Description
RendererId	id() Identifier mirrored on RendererId so Pp2FormatResult.Region.getRendererId() reflects which strategy actually produced the text for the region.
String	render(RegionParseOutcome outcome, Pp2TokenStream stream, Pp2FormatOptions opts) Render the outcome's region to its final text.

Method Detail

render

String render(RegionParseOutcome outcome,
              Pp2TokenStream stream,
              Pp2FormatOptions opts)

Render the outcome's region to its final text.

Parameters:

outcome - non-null parse outcome for the region. Implementations may assume RegionParseOutcome.getRange() and RegionParseOutcome.getParsedSql() are non-null. RegionParseOutcome.getParser() is non-null only for AST_OK outcomes.

stream - the engine's full Pp2TokenStream for the whole input script (token-based renderers slice into it via the outcome's range token indices)

opts - non-null pp2 options

Returns:

the formatted text for this region, or null (the only sentinel) to signal fall-through to the next renderer in the chain. An empty string is a valid rendering, not a fall-through.

id

RendererId id()

Identifier mirrored on RendererId so Pp2FormatResult.Region.getRendererId() reflects which strategy actually produced the text for the region.