001package gudusoft.gsqlparser.pp2.token;
002
003/**
004 * Side-channel role annotation on a {@link Pp2Token}.
005 *
006 * <p>Roles describe how the lexical island pipeline, the AST overlay
007 * annotator (S33), and the layout rules (S24-S29) should treat a token,
008 * orthogonal to the parser's {@code ETokenType}. They are computed by
009 * pp2 stages and stored on {@code Pp2Token.roles}; the wrapped
010 * {@link gudusoft.gsqlparser.TSourceToken} is never mutated.
011 *
012 * <p>Stored in an {@link java.util.EnumSet} per token. A token can carry
013 * multiple roles simultaneously (e.g., {@code KEYWORD_CLAUSE} +
014 * {@code STATEMENT_START}). Adding a role here is a non-breaking change
015 * for downstream consumers as long as they use {@code EnumSet}'s
016 * {@code contains} / {@code add} discipline.
017 */
018public enum TokenRole {
019
020    /** Master statement keyword (SELECT, INSERT, UPDATE, DELETE, MERGE, ...). */
021    KEYWORD_MASTER,
022
023    /** Clause keyword (FROM, WHERE, GROUP BY, ORDER BY, HAVING, JOIN, ...). */
024    KEYWORD_CLAUSE,
025
026    /** Generic keyword that is neither master nor clause (e.g., AS, DISTINCT). */
027    KEYWORD_GENERIC,
028
029    /** Plain identifier (table name, column name, alias). */
030    IDENTIFIER,
031
032    /** Quoted identifier (backticks, double-quotes, square brackets). */
033    QUOTED_IDENTIFIER,
034
035    /** Literal value (numeric, string, boolean, NULL). */
036    LITERAL,
037
038    /** Single-line comment: {@code -- ...} or {@code # ...}. */
039    COMMENT_LINE,
040
041    /** Block comment: {@code /* ... *}{@code /} (including nested where supported). */
042    COMMENT_BLOCK,
043
044    /** Hint comment, typically {@code /*+ ... *}{@code /} (Oracle, MySQL). */
045    HINT,
046
047    /** Punctuation: comma, semicolon, parenthesis, brackets. */
048    PUNCTUATION,
049
050    /** Operator: arithmetic, comparison, logical, concatenation, etc. */
051    OPERATOR,
052
053    /**
054     * Token lies inside a {@code --BEGIN_NO_FORMAT} / {@code --END_NO_FORMAT}
055     * block (or any other protected span). The lexical island renderer must
056     * emit it byte-exact.
057     */
058    NO_FORMAT_ZONE,
059
060    /** Template placeholder ({@code ${name}}, {@code {{name}}}, {@code #{name}}). */
061    TEMPLATE_PLACEHOLDER,
062
063    /**
064     * Marks a position where a scope (paren, BEGIN/END, CASE) is known to be
065     * incomplete in the source. The lexical island renderer treats this as a
066     * recovery hint.
067     */
068    INCOMPLETE_SCOPE_MARKER,
069
070    /** Boundary of an unrecoverable error region; assembler must preserve verbatim. */
071    ERROR_REGION_BOUNDARY,
072
073    /**
074     * Marks the start of a new top-level SQL statement. Set by the boundary
075     * detector (S11); used by the assembler (S15).
076     */
077    STATEMENT_START,
078
079    // -----------------------------------------------------------------
080    // AST overlay roles (S33) — derived from a parsed TCustomSqlStatement
081    // by AstOverlayAnnotator when Pp2FormatOptions.astOverlayEnabled is true.
082    // Off by default in v2: these roles are the annotation infrastructure
083    // a v3 AstOverlayRenderer will consume. The lexical island renderer and
084    // the guarded AST delegate do not read them in v2 (plan §5.4, §7.3/S33).
085    // -----------------------------------------------------------------
086
087    /** Token belongs to a SELECT-list result column (TResultColumn span). */
088    AST_SELECT_LIST_ITEM,
089
090    /** Token belongs to a table reference in a FROM clause (TTable span). */
091    AST_TABLE_REF,
092
093    /** Token belongs to a statement's WHERE clause (TWhereClause span). */
094    AST_WHERE_CONDITION
095}