gudusoft.gsqlparser.pp2

Class Pp2FormatOptions

Object

gudusoft.gsqlparser.pp2.Pp2FormatOptions

public class Pp2FormatOptions
extends Object

Configuration for the pp2 fault-tolerant SQL formatter.

Composes — does not extend — GFmtOpt. Composition is deliberate (plan §5.5): inheritance would couple pp2's option surface to every future change to GFmtOpt and force protected shims. The wrapped GFmtOpt carries all of pp's options (case rules, alignment, indent, etc.); the pp2-specific fields below extend that surface with the knobs pp2's region/recovery/fallback pipeline needs.

The from(GFmtOpt) factory copies field values by reflection into a freshly-allocated GFmtOpt so that:

• pp2 tuning never leaks back to the caller's GFmtOpt, and
• each Pp2FormatOptions carries its own sessionId so pp's session-keyed caches in FormatterFactory, ProcessorFactory, and MediatorFactory are not poisoned by pp2's invocations.

The reflection copier is risk R17's mitigation: when GFmtOpt gains a new public instance field, the copier picks it up automatically. The S2 test Pp2FormatOptionsTest verifies field-by-field equality after from().

Field semantics

• tolerantMode (true by default) — when true the engine never throws on a parse failure; it routes the region to the lexical fallback. When false the engine raises a Pp2ParseException with the parser diagnostics attached.
• maxLineWidth (default 120) — soft wrap target for the lexical island renderer. Hard guarantees are not made; identifier names and literals are never split.
• errorRegionStrategy (default Pp2FormatOptions.ErrorRegionStrategy.PRESERVE) — how to render a region the engine could not parse and the lexical fallback flagged as an ERROR_REGION.
• maxErrorRegionSize (default 10000 chars) — error regions larger than this are clamped; the overflow is emitted as a raw-text passthrough with an INFO diagnostic.
• maxRegionParseChars (default 200000 chars) — safety valve: regions whose source span exceeds this length skip per-region parsing entirely and go straight to the fallback renderer.
• commentPolicy (default CommentPolicy.PRESERVE) — how to anchor comments across region boundaries.
• showIndentMarkers (default false) — Delphi-style | debug rendering of indent levels in the lexical fallback output. Diagnostic only.
• astOverlayEnabled (default false) — feature flag for the v3 AST overlay annotator. Off in v2; flipping it on in v2 activates the annotator scaffold from slice S33 but does not change rendering output.

Mutability matches GFmtOpt's convention: fields are public and mutable so existing callers can tune options ergonomically. Concurrent mutation while a Pp2Formatter call is in flight is undefined.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Pp2FormatOptions.ErrorRegionStrategy Strategy for rendering parse-failed, lexical-fallback regions.

Field Summary

Fields

Modifier and Type	Field and Description
boolean	astOverlayEnabled Feature flag for the v3 AST overlay annotator.
CommentPolicy	commentPolicy Comment-anchoring policy across region boundaries.
Pp2FormatOptions.ErrorRegionStrategy	errorRegionStrategy How to render error regions.
int	maxErrorRegionSize Error regions larger than this are clamped.
int	maxLineWidth Soft line-wrap target (lexical island renderer only).
int	maxRegionParseChars Regions larger than this skip per-region parsing entirely.
boolean	showIndentMarkers Emit | markers at each indent level (debug output).
boolean	tolerantMode When true, parse failures route to fallback; never throws.

Method Summary

Modifier and Type	Method and Description
static Pp2FormatOptions	defaults() Construct with a fresh GFmtOpt carrying default values.
static Pp2FormatOptions	from(GFmtOpt gfmtOpt) Construct from an existing GFmtOpt by copying its public instance fields into a freshly-allocated GFmtOpt.
GFmtOpt	toGFmtOpt() Return the wrapped GFmtOpt.

Methods inherited from class Object

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

Field Detail

tolerantMode

public boolean tolerantMode

When true, parse failures route to fallback; never throws.

maxLineWidth

public int maxLineWidth

Soft line-wrap target (lexical island renderer only).

errorRegionStrategy

public Pp2FormatOptions.ErrorRegionStrategy errorRegionStrategy

How to render error regions.

maxErrorRegionSize

public int maxErrorRegionSize

Error regions larger than this are clamped.

maxRegionParseChars

public int maxRegionParseChars

Regions larger than this skip per-region parsing entirely.

commentPolicy

public CommentPolicy commentPolicy

Comment-anchoring policy across region boundaries.

showIndentMarkers

public boolean showIndentMarkers

Emit | markers at each indent level (debug output).

astOverlayEnabled

public boolean astOverlayEnabled

Feature flag for the v3 AST overlay annotator.

Method Detail

defaults

public static Pp2FormatOptions defaults()

Construct with a fresh GFmtOpt carrying default values. The underlying GFmtOpt is allocated via GFmtOptFactory.newInstance() so it gets a unique sessionId (used by pp's FormatterFactory caches).

from

public static Pp2FormatOptions from(GFmtOpt gfmtOpt)

Construct from an existing GFmtOpt by copying its public instance fields into a freshly-allocated GFmtOpt. The caller's instance is not retained; subsequent mutations to it are invisible to pp2, and pp2's mutations are invisible to the caller.

The sessionId field is final on GFmtOpt, so the copy carries the new fresh sessionId from GFmtOptFactory.newInstance() — not the source's.

Parameters:

gfmtOpt - must not be null

Throws:

NullPointerException - if gfmtOpt is null

toGFmtOpt

public GFmtOpt toGFmtOpt()

Return the wrapped GFmtOpt. pp2 hands this directly to FormatterFactory.pp() when the gudusoft.gsqlparser.pp2.engine.Pp2Engine (S16) dispatches a parseable region to the AST delegate.