Pp2FormatOptions (General SQL Parser Java Library Core 4.2.19 API)

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.

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.
`TransformPolicy`	`transformPolicy` Transformations of tokens or comments that the caller asked for and that pp2's content guards must therefore accept, in their exact expected form (see `TransformPolicy`).
`boolean`	`wholeDocumentFastPath` Whether a parseable input is handed straight to `pp`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Pp2FormatOptions`	`defaults()` Construct with a fresh `GFmtOpt` carrying default values.
`static Pp2FormatOptions`	`from(GFmtOpt gfmtOpt)`
`GFmtOpt`	`toGFmtOpt()` Return the wrapped `GFmtOpt`.
`static Pp2FormatOptions`	`wrap(GFmtOpt gfmtOpt)` Wrap an existing `GFmtOpt` without copying: pp2 formats with this very instance and its `sessionId`.

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
```
    Whether a parseable input is handed straight to pp.
    When true (the default) and the whole input parses, pp2 first formats the whole document with FormatterFactory.pp using these same options, and returns that text unchanged as an OK result provided it is token-equivalent to the input. Only when the whole-document parse fails, or pp throws, or pp's output drops or rewrites a token, does the regional pipeline run.
    This is what makes pp2 byte-identical to pp on parseable SQL: not an imitation of pp's layout rules, but pp itself. Set it to false only to exercise the regional pipeline directly (the regional pipeline reparses statement ranges independently, and its reassembled text was not byte-identical to whole-document pp on 60 of 1000 parseable corpus inputs — which is why this path exists).
  - 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.
  - transformPolicy
```
public TransformPolicy transformPolicy
```
    Transformations of tokens or comments that the caller asked for and that pp2's content guards must therefore accept, in their exact expected form (see TransformPolicy). Default: none, the plain content check.
- 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).
  - wrap
```
public static Pp2FormatOptions wrap(GFmtOpt gfmtOpt)
```
    Wrap an existing GFmtOpt without copying: pp2 formats with this very instance and its sessionId. Use it when the options must stay registered in GFmtOptFactory under that id, because parts of pp re-read their options by session id; the caller owns the instance and releases it (GFmtOptFactory.remove(java.lang.String)).
    
    Parameters:
    
    gfmtOpt - must not be null
    
    Throws:
    
    NullPointerException - if gfmtOpt is null
  - from
```
public static Pp2FormatOptions from(GFmtOpt gfmtOpt)
```
  - 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.

Class Pp2FormatOptions

Field semantics

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class Object

Field Detail

tolerantMode

maxLineWidth

errorRegionStrategy

maxErrorRegionSize

maxRegionParseChars

commentPolicy

showIndentMarkers

astOverlayEnabled

wholeDocumentFastPath

breakStatementsOnNewLine

transformPolicy

Method Detail

defaults

wrap

from

toGFmtOpt