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) — reserved for a future strict-mode switch. The current engine does not read this field and always recovers ordinary parse failures.
• maxLineWidth (default 120) — reserved soft-wrap target. The current pp2 renderers do not read this field.
• errorRegionStrategy (default Pp2FormatOptions.ErrorRegionStrategy.PRESERVE) — reserved strategy selector for lexical ERROR_REGIONs. The current engine does not read this field.
• maxErrorRegionSize (default 10000 chars) — caps the token span the island recognizer annotates as an ERROR_REGION. The current layout pipeline records that boundary but does not use it to select a different renderer.
• 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) — preserves comments across region boundaries. The alternative re-anchor/reflow policies remain experimental and are not fully implemented by the region assembler.
• showIndentMarkers (default false) — reserved diagnostic option. The current pp2 renderers do not read this field.
• 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 Reserved strategies for rendering parse-failed lexical regions.

Field Summary

Fields

Modifier and Type	Field and Description
boolean	astOverlayEnabled Feature flag for the v3 AST overlay annotator.
boolean	breakStatementsOnNewLine When true (default), consecutive top-level statements that share a physical line in the source (separated only by horizontal whitespace, with no line break) are placed on their own lines in the output.
CommentPolicy	commentPolicy Comment policy; PRESERVE is implemented, alternatives remain experimental.
Pp2FormatOptions.ErrorRegionStrategy	errorRegionStrategy Reserved error-region strategy selector; currently has no effect.
int	maxErrorRegionSize Maximum character span annotated as an ERROR_REGION by island recognition.
int	maxLineWidth Reserved soft line-wrap target; currently has no effect.
int	maxRegionParseChars Regions larger than this skip per-region parsing entirely.
boolean	showIndentMarkers Reserved indent-marker option; currently has no effect.
boolean	tolerantMode Reserved strict-mode switch; the current engine always recovers parse failures.
boolean	wholeDocumentFastPath When true (the default) and the whole input parses, pp2 first formats the whole document with FormatterFactory.pp using the same options and returns that text as an OK result if it is token-equivalent to the input.

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

Reserved strict-mode switch; the current engine always recovers parse failures.

maxLineWidth

public int maxLineWidth

Reserved soft line-wrap target; currently has no effect.

errorRegionStrategy

public Pp2FormatOptions.ErrorRegionStrategy errorRegionStrategy

Reserved error-region strategy selector; currently has no effect.

maxErrorRegionSize

public int maxErrorRegionSize

Maximum character span annotated as an ERROR_REGION by island recognition.

maxRegionParseChars

public int maxRegionParseChars

Regions larger than this skip per-region parsing entirely.

commentPolicy

public CommentPolicy commentPolicy

Comment policy; PRESERVE is implemented, alternatives remain experimental.

showIndentMarkers

public boolean showIndentMarkers

Reserved indent-marker option; currently has no effect.

astOverlayEnabled

public boolean astOverlayEnabled

Feature flag for the v3 AST overlay annotator.

wholeDocumentFastPath

public boolean wholeDocumentFastPath

When true (the default) and the whole input parses, pp2 first formats the whole document with FormatterFactory.pp using the same options and returns that text as an OK result if it is token-equivalent to the input. Only when the whole-document parse or pp fails, or pp changes a token, does the regional pipeline run. This gives byte parity with pp on parseable input; set to false to exercise the regional pipeline directly.

breakStatementsOnNewLine

public boolean breakStatementsOnNewLine

When true (default), consecutive top-level statements that share a physical line in the source (separated only by horizontal whitespace, with no line break) are placed on their own lines in the output. When false, the original inter-statement whitespace is preserved verbatim — the legacy behaviour, which could leave several statements running together on one line. Gaps that already contain a line break, or that contain comments / non-whitespace trivia, are always preserved verbatim regardless of this flag.

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.