GSP Java SQL formatter options¶
This is the complete reference for the 70 public fields on
GFmtOpt in GSP Java. It is generated from the source Javadoc,
so option behavior and website documentation have one source of truth.
For the parse-and-format workflow and runnable recipes, start with
Format (pretty-print) SQL.
Java has one edition-only option, maxSelectListColumn, and implements both plain SQL and syntax-highlighted HTML output.
Configure related options together
A list style, its comma style, and its first-item newline are separate
controls. Comma placement generally produces line breaks only with a
stacked style. Cpmugly compact mode bypasses most normal layout controls.
Java session registration
GFmtOptFactory.newInstance() returns a fresh option object, but the
all-statement pass recovers some settings through the session registry.
For emptyLines, tabs, comments, or line numbers, use the overload with
an application-managed unique session id so the same object is registered.
Categories¶
Allowed values¶
These enums are shared by several fields. Read their value semantics before combining a layout field with a comma, alignment, case, or blank-line field.
TAlignStyle¶
| Value | Meaning |
|---|---|
AsStacked |
Put later list items on aligned lines using the selected comma style. |
AsWrapped |
Keep list items on the current line and normalize separators to spaces. |
TLinefeedsCommaOption¶
| Value | Meaning |
|---|---|
LfAfterComma |
Keep the comma at the end of the previous item, then break the line. |
LfbeforeCommaWithSpace |
Break before the comma and insert one space between it and the next item. |
LfBeforeComma |
Break before the comma without inserting a following space. |
TAlignOption¶
| Value | Meaning |
|---|---|
AloLeft |
Keep the text's left edge fixed and append padding on the right. |
AloRight |
Prepend padding so the text's right edge aligns with the widest item. |
TCaseOption¶
| Value | Meaning |
|---|---|
CoUppercase |
Convert every character to upper case. |
CoLowercase |
Convert every character to lower case. |
CoNoChange |
Preserve the token text exactly as parsed. |
CoInitCap |
Upper-case the first character of each space-delimited word and lower-case the rest. |
TEmptyLinesOption¶
| Value | Meaning |
|---|---|
EloMergeIntoOne |
Collapse two or more separating line breaks to one blank line. |
EloRemove |
Remove blank lines while retaining the newline that separates statements. |
EloPreserve |
Reproduce the number of blank lines present in the input. |
TCompactMode¶
| Value | Meaning |
|---|---|
CpmNone |
Run the normal statement-specific pretty-printing pipeline. |
Cpmugly |
Skip normal layout and emit compact token text, wrapping at the configured line width. |
GOutputFmt¶
| Value | Meaning |
|---|---|
ofSql |
Plain formatted SQL; supported. |
ofCsharp |
Legacy C# source renderer selector; not implemented by the active formatter. |
ofCsharpsbd |
Legacy C# StringBuilder renderer selector; not implemented by the active formatter. |
ofvb |
Legacy Visual Basic source renderer selector; not implemented by the active formatter. |
ofvbsbd |
Legacy Visual Basic StringBuilder renderer selector; not implemented by the active formatter. |
ofjava |
Legacy Java source renderer selector; not implemented by the active formatter. |
ofjavasbf |
Legacy Java StringBuffer renderer selector; not implemented by the active formatter. |
ofvc |
Legacy Visual C++ source renderer selector; not implemented by the active formatter. |
ofpascal |
Legacy Pascal source renderer selector; not implemented by the active formatter. |
ofphp |
Legacy PHP source renderer selector; not implemented by the active formatter. |
ofproc |
Legacy embedded-C renderer selector; not implemented by the active formatter. |
ofprocobol |
Legacy embedded-COBOL renderer selector; not implemented by the active formatter. |
ofhtml |
Syntax-highlighted HTML output; supported. |
ofhtml2 |
Legacy alternate HTML renderer selector; not implemented by the active formatter. |
ofhtmlkeeplayout |
Legacy layout-preserving HTML renderer selector; not implemented by the active formatter. |
ofhtmlkeeplayout2 |
Legacy alternate layout-preserving HTML renderer selector; not implemented by the active formatter. |
ofhtmlkeeplayoutmodifycase |
Legacy case-modifying HTML renderer selector; not implemented by the active formatter. |
ofhtmlkeeplayout2modifycase |
Legacy alternate case-modifying HTML renderer selector; not implemented by the active formatter. |
oftxtmodifycase |
Legacy case-modifying text renderer selector; not implemented by the active formatter. |
ofxml |
Legacy XML renderer selector; not implemented by the active formatter. |
ofdbobject |
Legacy database-object renderer selector; not implemented by the active formatter. |
ofrtf |
Legacy rich-text renderer selector; not implemented by the active formatter. |
ofrtfkeeplayout |
Legacy layout-preserving rich-text renderer selector; not implemented by the active formatter. |
ofrtfkeeplayoutmodifycase |
Legacy case-modifying rich-text renderer selector; not implemented by the active formatter. |
ofFromCSharp |
Legacy C#-input conversion selector; not implemented by the active formatter. |
ofFromVB |
Legacy Visual Basic-input conversion selector; not implemented by the active formatter. |
ofFromVC |
Legacy Visual C++-input conversion selector; not implemented by the active formatter. |
ofFromJava |
Legacy Java-input conversion selector; not implemented by the active formatter. |
ofFromPhp |
Legacy PHP-input conversion selector; not implemented by the active formatter. |
ofFromPascal |
Legacy Pascal-input conversion selector; not implemented by the active formatter. |
ofUnknown |
Unknown output selector; treated as plain SQL by the active formatter. |
Lifecycle and advanced controls¶
sessionId¶
- Type:
String - Default: Supplied to the constructor
Identifies the formatting session used by formatter, processor, and mediator caches. Use a unique id for independently configured concurrent calls; the id is not rendered in the output.
opearateSourceToken¶
- Type:
boolean - Default:
true
Enables the low-level source-token mutation operations that implement formatting. Setting this to false makes token add/remove helpers ignore requests and therefore disables most formatting; it is intended for diagnostics, not as a preserve-layout mode.
SELECT list and query clauses¶
selectColumnlistStyle¶
- Type:
TAlignStyle - Default:
TAlignStyle.AsStacked
Chooses stacked or wrapped layout for SELECT result columns and is also reused by GROUP BY and ORDER BY lists. Stacked layout permits line breaks according to selectColumnlistComma; wrapped layout keeps items on the current line. Alias alignment is applied only to stacked lists.
selectColumnlistComma¶
- Type:
TLinefeedsCommaOption - Default:
TLinefeedsCommaOption.LfAfterComma
Chooses whether a comma ends the previous line or begins the next line in stacked SELECT, GROUP BY, and ORDER BY lists. The setting has no line-break effect when selectColumnlistStyle is wrapped.
selectItemInNewLine¶
- Type:
boolean - Default:
false
Places the first SELECT item on a line after SELECT. The same switch also places the first GROUP BY and ORDER BY item, and the HAVING expression, after their clause keywords; subsequent item breaks are controlled by the list style and comma option.
alignAliasInSelectList¶
- Type:
boolean - Default:
true
Pads stacked SELECT expressions so their explicit or implicit aliases begin in the same column. It is ignored for wrapped lists and may be skipped for exceptionally wide lists to avoid excessive padding.
treatDistinctAsVirtualColumn¶
- Type:
boolean - Default:
false
Adds a synthetic DISTINCT result-column node to the parsed SELECT list so it participates in stacking and comma-layout calculations. This mutates the statement's result-column list for formatting, although the rendered SQL semantics are unchanged.
FROM, JOIN, and WHERE¶
selectFromclauseStyle¶
- Type:
TAlignStyle - Default:
TAlignStyle.AsStacked
Chooses stacked or wrapped layout for comma-separated table sources in a FROM clause. JOIN clauses have their own newline and alignment controls.
selectFromclauseComma¶
- Type:
TLinefeedsCommaOption - Default:
TLinefeedsCommaOption.LfAfterComma
Positions commas for stacked comma-separated FROM items. It is effective only when selectFromclauseStyle is stacked.
fromClauseInNewLine¶
- Type:
boolean - Default:
false
Places the first table source on a new indented line after FROM (and the corresponding INTO table source where that clause shares this processor). When false, one space separates the clause keyword and first source.
selectFromclauseJoinOnInNewline¶
- Type:
boolean - Default:
true
Places the ON condition of a JOIN on a separate line. JOIN keywords are always normalized onto their own lines by the JOIN processor; this switch controls the additional break before ON.
alignJoinWithFromKeyword¶
- Type:
boolean - Default:
false
Aligns the beginning of JOIN phrases with the FROM keyword rather than with the first table source. It does not control whether ON starts a new line; use selectFromclauseJoinOnInNewline for that.
andOrUnderWhere¶
- Type:
boolean - Default:
false
Aligns leading AND and OR operators under the WHERE keyword. When false, boolean continuations use the expression formatter's normal indentation.
INSERT and general lists¶
insertColumnlistStyle¶
- Type:
TAlignStyle - Default:
TAlignStyle.AsStacked
Chooses stacked or wrapped layout for the target-column list of INSERT. Comma placement comes from defaultCommaOption rather than the SELECT-specific comma option.
insertValuelistStyle¶
- Type:
TAlignStyle - Default:
TAlignStyle.AsStacked
Chooses stacked or wrapped layout for each INSERT VALUES list. Comma placement comes from defaultCommaOption.
defaultCommaOption¶
- Type:
TLinefeedsCommaOption - Default:
TLinefeedsCommaOption.LfAfterComma
Provides comma placement for formatter lists without a dedicated comma setting, including INSERT columns/values, UPDATE SET items, and CREATE TABLE columns and constraints.
defaultAligntype¶
- Type:
TAlignStyle - Default:
TAlignStyle.AsStacked
Provides stacked or wrapped layout for lists without a dedicated style, notably UPDATE SET and CREATE TABLE lists. INSERT has separate style fields but still uses defaultCommaOption for commas.
CREATE TABLE¶
beStyleCreatetableLeftBEOnNewline¶
- Type:
boolean - Default:
false
Places the opening parenthesis of a CREATE TABLE column list on a new line and indents it by indentLen. If list items are also placed on new lines, they receive one additional indentation level.
beStyleCreatetableRightBEOnNewline¶
- Type:
boolean - Default:
false
Places the closing parenthesis of a CREATE TABLE column list on its own line. Its indentation accounts for whether the opening parenthesis was also moved to a new line.
createtableListitemInNewLine¶
- Type:
boolean - Default:
false
Places the first CREATE TABLE column or constraint on a new line after the opening parenthesis. Remaining items follow defaultAligntype and defaultCommaOption.
createtableFieldlistAlignOption¶
- Type:
TAlignOption - Default:
TAlignOption.AloLeft
Left- or right-aligns CREATE TABLE column names within the widest column- name width. It is applied only when defaultAligntype is stacked.
Indentation and procedural blocks¶
indentLen¶
- Type:
Integer - Default:
2
Sets the general indentation increment, in columns, used by nested clauses, expressions, CTE bodies, parameters, and many statement processors. More specialized indentation options add to, rather than replace, this value.
useTab¶
- Type:
Boolean - Default:
false
Enables the final tab-alignment pass. The formatter first computes spaces, then pads each indented line to a multiple of tabSize; this option does not replace all indentation characters with literal tab characters.
tabSize¶
- Type:
Integer - Default:
2
Defines the tab-stop width used by the final tab-alignment pass when useTab is enabled. Use a positive value.
beStyleFunctionBodyIndent¶
- Type:
Integer - Default:
2; currently has no effect
Reserved compatibility setting for stored-routine body indentation. The active formatter currently does not read this field; use beStyleBlockIndentSize and indentLen for effective body indentation.
beStyleBlockLeftBEOnNewline¶
- Type:
Boolean - Default:
true
Places a procedural BEGIN token on a new line. This is used by PL/SQL-like blocks and by SQL Server BEGIN/END block formatting, with vendor-specific paths applying the related indentation settings.
beStyleBlockLeftBEIndentSize¶
- Type:
Integer - Default:
2
Adds columns to the containing statement's indentation for a BEGIN token moved to a new line. It is meaningful when beStyleBlockLeftBEOnNewline is true.
beStyleBlockRightBEIndentSize¶
- Type:
Integer - Default:
2
Controls END indentation for block paths where BEGIN remains on the current line. When BEGIN is moved, those paths align END using the BEGIN indent instead, so this value may be ignored.
beStyleBlockIndentSize¶
- Type:
Integer - Default:
2
Adds indentation to statements inside BEGIN/END blocks and to returned query bodies in supported CREATE FUNCTION and CREATE VIEW forms. It is measured relative to the enclosing block marker.
beStyleIfElseSingleStmtIndentSize¶
- Type:
Integer - Default:
2
Adds indentation to a single statement controlled by IF or ELSE when the body is not represented as a BEGIN/END block. Block bodies instead use the block indentation options.
CASE expressions¶
caseWhenThenInSameLine¶
- Type:
Boolean - Default:
false
Keeps each WHEN condition and its THEN keyword on one line when true. When false, THEN starts a new line and its indentation additionally uses indentCaseThen.
indentCaseFromSwitch¶
- Type:
Integer - Default:
2
Indents WHEN, ELSE, and END relative to the CASE keyword. The value is an absolute number of columns added at that CASE nesting level.
indentCaseThen¶
- Type:
Integer - Default:
0
Adds indentation to a line-broken THEN relative to its WHEN indentation. It is ignored when caseWhenThenInSameLine is true.
Keyword alignment and capitalization¶
selectKeywordsAlignOption¶
- Type:
TAlignOption - Default:
TAlignOption.AloLeft
Left- or right-aligns multiword and single-word query clause labels such as SELECT, FROM, WHERE, GROUP BY, HAVING, and ORDER BY within their shared keyword width.
caseKeywords¶
- Type:
TCaseOption - Default:
TCaseOption.CoUppercase
Converts SQL keyword tokens to the selected case. Datatypes and recognized function names use their dedicated case settings instead.
caseIdentifier¶
- Type:
TCaseOption - Default:
TCaseOption.CoNoChange
Converts unquoted identifier tokens that are not recognized as datatypes or function names. Changing case can change semantics in case-sensitive databases, so preserve case unless that transformation is intentional.
caseQuotedIdentifier¶
- Type:
TCaseOption - Default:
TCaseOption.CoNoChange
Converts double-quoted identifier contents while preserving the quote characters. Quoted identifiers are frequently case-sensitive; use any value other than no-change with care.
caseFuncname¶
- Type:
TCaseOption - Default:
TCaseOption.CoInitCap
Converts tokens recognized by the parser as function names, including built-in and user-defined calls where classification is available.
caseDatatype¶
- Type:
TCaseOption - Default:
TCaseOption.CoUppercase
Converts tokens recognized as datatype names. This classification takes precedence over the general keyword and identifier case settings.
Whitespace and parentheses¶
wsPaddingOperatorArithmetic¶
- Type:
Boolean - Default:
true
Inserts one space on both sides of recognized binary arithmetic and comparison operators. Unary plus and minus are kept adjacent to their operand regardless of this setting.
wsPaddingParenthesesInFunction¶
- Type:
Boolean - Default:
false
Inserts one space just inside the parameter-list parentheses of CREATE FUNCTION, PROCEDURE, PACKAGE, and TRIGGER declarations when parameters are present. It does not affect ordinary function calls.
wsPaddingParenthesesInExpression¶
- Type:
Boolean - Default:
true
Inserts one space just inside parentheses that group an expression, for example ( a + b ). Subqueries, function calls, and datatype parameters use separate options.
wsPaddingParenthesesOfSubQuery¶
- Type:
Boolean - Default:
false
Inserts one space just inside parentheses that enclose a formatted subquery. Internal subquery line breaks and indentation are still produced by the nested statement formatter.
wsPaddingParenthesesInFunctionCall¶
- Type:
Boolean - Default:
false
Inserts one space just inside ordinary function-call parentheses. Stored- routine declaration parentheses use wsPaddingParenthesesInFunction instead.
wsPaddingParenthesesOfTypename¶
- Type:
Boolean - Default:
false
Inserts one space just inside datatype-parameter parentheses, for example VARCHAR( 20 ). It applies only when the parser classifies the node as a type name.
CTEs and declarations¶
cteNewlineBeforeAs¶
- Type:
Boolean - Default:
true
Places the AS keyword of each common table expression on a new line aligned under the CTE name area. When false, AS follows the CTE header after one space; the CTE query itself is formatted in both cases.
linebreakAfterDeclare¶
- Type:
Boolean - Default:
false
Places the first variable declaration on a new indented line after DECLARE. Later declaration items are always stacked by the DECLARE formatter.
Routine declarations and EXEC¶
parametersStyle¶
- Type:
TAlignStyle - Default:
TAlignStyle.AsStacked
Chooses stacked or wrapped layout for stored-routine, package, trigger, and supported CREATE VIEW parameter declarations. Stacked parameters also have their names/types aligned by the parameter formatter.
parametersComma¶
- Type:
TLinefeedsCommaOption - Default:
TLinefeedsCommaOption.LfAfterComma
Positions commas for stacked stored-routine parameter declarations. It is effective when parametersStyle is stacked.
beStyleFunctionLeftBEOnNewline¶
- Type:
Boolean - Default:
false
Places the opening parenthesis of a stored-routine parameter list on a new line. The setting applies only when a parameter declaration list exists.
beStyleFunctionLeftBEIndentSize¶
- Type:
Integer - Default:
0
Adds columns to the current indentation of a stored-routine opening parenthesis moved to a new line. It is ignored unless beStyleFunctionLeftBEOnNewline is true.
beStyleFunctionRightBEOnNewline¶
- Type:
Boolean - Default:
true
Places the closing parenthesis of a stored-routine parameter list on a new line. The setting applies only when a parameter declaration list exists.
beStyleFunctionRightBEIndentSize¶
- Type:
Integer - Default:
0
Adds columns relative to the routine declaration when a parameter-list closing parenthesis is moved to a new line. It is ignored unless beStyleFunctionRightBEOnNewline is true.
beStyleFunctionFirstParamInNewline¶
- Type:
Boolean - Default:
false
Places the first stored-routine parameter on a new line and indents it one general indentation level beyond its current parameter-list indentation. Subsequent parameters follow the parameter style and comma settings.
linebreakBeforeParamInExec¶
- Type:
Boolean - Default:
true
Places the first SQL Server EXEC/EXECUTE argument on a new line, indented by indentLen from the statement. It does not control stored-routine declaration parameters.
Blank lines and batches¶
emptyLines¶
- Type:
TEmptyLinesOption - Default:
TEmptyLinesOption.EloMergeIntoOne
Determines how blank lines found between top-level statements are handled: remove them, collapse them to one blank line, or preserve their count. Statement-separating newlines themselves are always retained.
insertBlankLineInBatchSqls¶
- Type:
Boolean - Default:
false
Inserts a blank line between statements inside supported BEGIN/END batches. It is applied in addition to the general emptyLines policy.
noEmptyLinesBetweenMultiSetStmts¶
- Type:
Boolean - Default:
false
Suppresses the formatter's otherwise automatic blank line between adjacent SET or DECLARE-family statements. It does not remove ordinary separator newlines and does not override unrelated batch blank-line insertion.
Line numbers¶
linenumberEnabled¶
- Type:
Boolean - Default:
false
Prefixes every output line with a zero-padded line number. Width is based on the total formatted line count; margins are controlled by the line-number margin settings.
linenumberZeroBased¶
- Type:
Boolean - Default:
false(one-based numbering)
Starts generated line numbers at zero when true, or one when false. It has no effect unless linenumberEnabled is enabled.
linenumberLeftMargin¶
- Type:
Integer - Default:
0
Inserts this many spaces before each generated line number. It has no effect unless linenumberEnabled is enabled.
linenumberRightMargin¶
- Type:
Integer - Default:
2
Inserts this many spaces between each generated line number and the SQL text. It has no effect unless linenumberEnabled is enabled.
Function calls¶
functionCallParametersStyle¶
- Type:
TAlignStyle - Default:
TAlignStyle.AsWrapped
Chooses stacked or wrapped layout for argument lists in ordinary function calls. This is independent from the stored-routine declaration parameter style.
functionCallParametersComma¶
- Type:
TLinefeedsCommaOption - Default:
TLinefeedsCommaOption.LfAfterComma
Positions commas when ordinary function-call arguments use stacked layout. It has no line-break effect while functionCallParametersStyle is wrapped.
Comments, compact mode, and wrapping¶
removeComment¶
- Type:
Boolean - Default:
false
Removes ordinary line and block comments before formatting and reparses the modified token stream. Oracle optimizer hints beginning with /*+ are preserved. Because removal mutates the parser's token list, use a fresh parser if the original comments are needed later.
compactMode¶
- Type:
TCompactMode - Default:
TCompactMode.CpmNone
Selects normal pretty-printing or compact output. Cpmugly short-circuits statement-specific layout, normalizes the token stream, and wraps only when lineWidth is exceeded; most other layout options are therefore ignored.
lineWidth¶
- Type:
Integer - Default:
99
Sets the maximum line width used by compact mode. It is a soft limit: indivisible tokens longer than the value can still exceed it. The active normal pretty-printing pipeline does not currently use this field.
maxSelectListColumn¶
- Type:
Integer - Default:
20. This option is available only in GSP Java
Limits how many items are stacked at once in large SELECT-style lists. When a list exceeds the threshold, the comma processor emits groups of this many items per line and alias alignment may be skipped; use Integer.MAX_VALUE to disable the threshold.
Output rendering¶
outputFmt¶
- Type:
GOutputFmt - Default:
GOutputFmt.ofSql
Selects the renderer used after token formatting. The active formatter supports GOutputFmt.ofSql and GOutputFmt.ofhtml; GOutputFmt.ofUnknown falls back to SQL, while the other legacy enum values currently throw UnsupportedOperationException. After HTML output initializes the static renderer, later FormatterFactory.pp calls reuse it until FormatterFactory.setOutputConfig(null) is called.
tabHtmlString¶
- Type:
String - Default:
" "
Replaces each literal tab in HTML output with this string. It is used only by the Java HTML renderer (outputFmt == ofhtml) and is independent of the tab-stop calculation controlled by useTab and tabSize.
Keeping this page current¶
Edit the field or enum documentation in the corresponding GSP source tree, then regenerate both references:
1 2 | |