flowchart TB
    subgraph Parser["Parser 模块 (src/backend/parser)"]
        direction TB

        Entry[raw_parser 入口函数] --> Init[初始化阶段]
        Init --> Scanner[scanner_init<br/>初始化 Lexer]
        Init --> ParserInit[parser_init<br/>初始化 Bison]

        Scanner --> Lex[base_yylex<br/>词法分析器]
        ParserInit --> Gram[base_yyparse<br/>语法分析器]

        Lex -->|Token 流| Gram

        Gram --> Actions[语法动作<br/>构建 AST 节点]
        Actions --> Tree[生成 Parse Tree]

        Tree --> Cleanup[scanner_finish<br/>清理资源]
        Cleanup --> Return[返回 List 结构]
    end

    subgraph External["外部输入"]
        SQL[SQL 文本]
        Mode[RawParseMode]
    end

    subgraph Keywords["关键字表"]
        KW[ScanKeywords<br/>SQL 关键字列表]
        KWTokens[ScanKeywordTokens<br/>关键字到 Token 映射]
    end

    subgraph Output["输出结果"]
        RawStmt[RawStmt 节点]
        SelectStmt[SelectStmt]
        InsertStmt[InsertStmt]
        UpdateStmt[UpdateStmt]
        DeleteStmt[DeleteStmt]
        UtilityStmt[DDL/DCL 语句]
    end

    SQL --> Entry
    Mode --> Entry
    KW --> Scanner
    KWTokens --> Scanner

    Return --> RawStmt
    RawStmt --> SelectStmt
    RawStmt --> InsertStmt
    RawStmt --> UpdateStmt
    RawStmt --> DeleteStmt
    RawStmt --> UtilityStmt

    subgraph NextStage["后续阶段"]
        Analyzer[Analyzer<br/>语义分析]
    end

    Return --> Analyzer

/* src/include/nodes/parsenodes.h */
typedef struct RawStmt
{
    NodeTag     type;           /* 节点类型标识：T_RawStmt */
    Node       *stmt;           /* 实际的语句节点（SelectStmt/InsertStmt 等） */
    int         stmt_location;  /* 语句在原始文本中的起始位置（字节偏移） */
    int         stmt_len;       /* 语句长度（字节数），-1 表示未知 */
} RawStmt;

/* src/include/nodes/parsenodes.h */
typedef struct SelectStmt
{
    NodeTag     type;           /* 节点类型：T_SelectStmt */

    List       *distinctClause; /* DISTINCT 子句（NIL 表示无 DISTINCT） */
    IntoClause *intoClause;     /* INTO 子句（用于 SELECT INTO） */
    List       *targetList;     /* 选择列表（ResTarget 节点列表） */
    List       *fromClause;     /* FROM 子句（RangeVar 等节点列表） */
    Node       *whereClause;    /* WHERE 条件表达式 */
    List       *groupClause;    /* GROUP BY 子句（GroupingClause 节点列表） */
    bool        groupDistinct;  /* GROUP BY DISTINCT */
    Node       *havingClause;   /* HAVING 条件表达式 */
    List       *windowClause;   /* WINDOW 定义列表 */

    List       *valuesLists;    /* VALUES 子句（嵌套 List，用于 VALUES 语法） */

    List       *sortClause;     /* ORDER BY 子句（SortBy 节点列表） */
    Node       *limitOffset;    /* OFFSET 表达式 */
    Node       *limitCount;     /* LIMIT 表达式 */
    LimitOption limitOption;    /* LIMIT 选项（WITH TIES 等） */

    List       *lockingClause;  /* FOR UPDATE/SHARE 子句 */
    WithClause *withClause;     /* WITH 子句（CTE） */

    /* 集合操作（UNION/INTERSECT/EXCEPT） */
    SetOperation op;            /* 集合操作类型 */
    bool        all;            /* ALL 标志（如 UNION ALL） */
    struct SelectStmt *larg;    /* 左操作数（用于集合操作） */
    struct SelectStmt *rarg;    /* 右操作数（用于集合操作） */
} SelectStmt;

/* src/include/nodes/parsenodes.h */
typedef struct InsertStmt
{
    NodeTag     type;           /* 节点类型：T_InsertStmt */

    RangeVar   *relation;       /* 目标表 */
    List       *cols;           /* 列名列表（ResTarget 节点，仅包含列名） */
    Node       *selectStmt;     /* 数据源（SelectStmt 或 VALUES） */
    OnConflictClause *onConflictClause; /* ON CONFLICT 子句 */
    List       *returningList;  /* RETURNING 子句 */
    WithClause *withClause;     /* WITH 子句（CTE） */
    OverridingKind override;    /* OVERRIDING SYSTEM/USER VALUE */
} InsertStmt;

/* src/include/nodes/parsenodes.h */
typedef struct UpdateStmt
{
    NodeTag     type;           /* 节点类型：T_UpdateStmt */

    RangeVar   *relation;       /* 目标表 */
    List       *targetList;     /* SET 子句（ResTarget 节点列表） */
    Node       *whereClause;    /* WHERE 条件表达式 */
    List       *fromClause;     /* FROM 子句（用于多表 UPDATE） */
    List       *returningList;  /* RETURNING 子句 */
    WithClause *withClause;     /* WITH 子句（CTE） */
} UpdateStmt;

UPDATE users SET status = orders.status
FROM orders
WHERE users.id = orders.user_id;

/* src/include/nodes/parsenodes.h */
typedef struct DeleteStmt
{
    NodeTag     type;           /* 节点类型：T_DeleteStmt */

    RangeVar   *relation;       /* 目标表 */
    List       *usingClause;    /* USING 子句（用于多表 DELETE） */
    Node       *whereClause;    /* WHERE 条件表达式 */
    List       *returningList;  /* RETURNING 子句 */
    WithClause *withClause;     /* WITH 子句（CTE） */
} DeleteStmt;

DELETE FROM users
USING orders
WHERE users.id = orders.user_id AND orders.status = 'cancelled';

classDiagram
    class Node {
        <<abstract>>
        +NodeTag type
    }

    class RawStmt {
        +NodeTag type
        +Node *stmt
        +int stmt_location
        +int stmt_len
    }

    class SelectStmt {
        +NodeTag type
        +List *distinctClause
        +List *targetList
        +List *fromClause
        +Node *whereClause
        +List *groupClause
        +Node *havingClause
        +List *sortClause
        +Node *limitCount
        +Node *limitOffset
        +SetOperation op
        +SelectStmt *larg
        +SelectStmt *rarg
    }

    class InsertStmt {
        +NodeTag type
        +RangeVar *relation
        +List *cols
        +Node *selectStmt
        +OnConflictClause *onConflictClause
        +List *returningList
    }

    class UpdateStmt {
        +NodeTag type
        +RangeVar *relation
        +List *targetList
        +Node *whereClause
        +List *fromClause
        +List *returningList
    }

    class DeleteStmt {
        +NodeTag type
        +RangeVar *relation
        +List *usingClause
        +Node *whereClause
        +List *returningList
    }

    class CreateStmt {
        +NodeTag type
        +RangeVar *relation
        +List *tableElts
        +List *inhRelations
        +PartitionSpec *partspec
        +OnCommitAction oncommit
    }

    class List {
        +int length
        +ListCell *head
    }

    class RangeVar {
        +char *catalogname
        +char *schemaname
        +char *relname
        +int location
    }

    class ResTarget {
        +char *name
        +Node *val
        +int location
    }

    Node <|-- RawStmt
    Node <|-- SelectStmt
    Node <|-- InsertStmt
    Node <|-- UpdateStmt
    Node <|-- DeleteStmt
    Node <|-- CreateStmt

    RawStmt --> Node : stmt
    SelectStmt --> List : targetList
    SelectStmt --> List : fromClause
    SelectStmt --> SelectStmt : larg, rarg
    InsertStmt --> RangeVar : relation
    InsertStmt --> Node : selectStmt
    UpdateStmt --> RangeVar : relation
    UpdateStmt --> List : targetList
    DeleteStmt --> RangeVar : relation
    List --> ResTarget : element
    List --> RangeVar : element

Node *node = (Node *) stmt;
switch (nodeTag(node)) {
    case T_SelectStmt:
        SelectStmt *select = (SelectStmt *) node;
        /* 处理 SELECT 语句 */
        break;
    case T_InsertStmt:
        InsertStmt *insert = (InsertStmt *) node;
        /* 处理 INSERT 语句 */
        break;
    /* ... */
}

/* 函数参数说明 */
const char *str;        /* SQL 文本字符串（以 \0 结尾） */
RawParseMode mode;      /* 解析模式（枚举） */

/* 返回值说明 */
List *result;  /* 解析树列表，失败时返回 NIL */

/* src/backend/parser/parser.c */
List *
raw_parser(const char *str, RawParseMode mode)
{
    core_yyscan_t yyscanner;
    base_yy_extra_type yyextra;
    int yyresult;

    /* 1. 初始化词法分析器（Flex 扫描器） */
    yyscanner = scanner_init(str, &yyextra.core_yy_extra,
                             &ScanKeywords, ScanKeywordTokens);

    /* 2. 根据解析模式设置前瞻 Token */
    if (mode == RAW_PARSE_DEFAULT)
        yyextra.have_lookahead = false;  /* 默认模式：无前瞻 */
    else
    {
        /* 其他模式：注入模式 Token 作为前瞻，引导语法选择特定规则 */
        static const int mode_token[] = {
            [RAW_PARSE_DEFAULT] = 0,
            [RAW_PARSE_TYPE_NAME] = MODE_TYPE_NAME,
            [RAW_PARSE_PLPGSQL_EXPR] = MODE_PLPGSQL_EXPR,
            /* ... 其他模式 ... */
        };
        yyextra.have_lookahead = true;
        yyextra.lookahead_token = mode_token[mode];
        yyextra.lookahead_yylloc = 0;
        yyextra.lookahead_end = NULL;
    }

    /* 3. 初始化语法分析器（Bison 解析器） */
    parser_init(&yyextra);

    /* 4. 执行语法分析 */
    yyresult = base_yyparse(yyscanner);

    /* 5. 清理扫描器资源 */
    scanner_finish(yyscanner);

    /* 6. 检查解析结果 */
    if (yyresult)  /* 非零表示错误 */
        return NIL;

    /* 7. 返回解析树列表 */
    return yyextra.parsetree;
}

PostgresMain (postgres.c)
  → exec_simple_query (postgres.c)
    → pg_parse_query (postgres.c)
      → raw_parser (parser.c)  ← 当前函数

/* src/backend/tcop/postgres.c */
List *
pg_parse_query(const char *query_string)
{
    List *raw_parsetree_list;

    /* 调用解析器，使用默认模式 */
    raw_parsetree_list = raw_parser(query_string, RAW_PARSE_DEFAULT);

    /* （此处省略查询重写和规范化处理） */

    return raw_parsetree_list;
}

/* src/backend/tcop/postgres.c */
static void
exec_simple_query(const char *query_string)
{
    List *parsetree_list;
    ListCell *parsetree_item;

    /* 1. 解析 SQL 文本 */
    parsetree_list = pg_parse_query(query_string);

    /* 2. 遍历每条语句，逐个执行 */
    foreach(parsetree_item, parsetree_list)
    {
        RawStmt *parsetree = lfirst_node(RawStmt, parsetree_item);

        /* 3. 语义分析（Analyzer） */
        Query *query = parse_analyze_fixedparams(parsetree, query_string, NULL, 0, NULL);

        /* 4. 查询重写（Rewriter） */
        List *querytree_list = pg_rewrite_query(query);

        /* 5. 生成执行计划（Planner） */
        /* 6. 执行计划（Executor） */
        /* （此处省略后续步骤） */
    }
}

plpgsql_compile (pl_comp.c)
  → plpgsql_parse_word (pl_comp.c)
    → raw_parser (parser.c, mode = RAW_PARSE_PLPGSQL_EXPR)

/* src/pl/plpgsql/src/pl_comp.c */
PLpgSQL_expr *
plpgsql_parse_word(const char *word)
{
    List *parsetree;
    RawStmt *rawstmt;

    /* 使用 PL/pgSQL 表达式模式解析 */
    parsetree = raw_parser(word, RAW_PARSE_PLPGSQL_EXPR);

    /* 提取唯一的 RawStmt 节点 */
    rawstmt = linitial_node(RawStmt, parsetree);

    /* 构造 PLpgSQL_expr 结构 */
    /* （此处省略表达式包装代码） */

    return expr;
}

sequenceDiagram
    autonumber
    participant Client as 客户端
    participant Backend as Backend 进程
    participant PG as PostgresMain
    participant ESQ as exec_simple_query
    participant PPQ as pg_parse_query
    participant RP as raw_parser
    participant SI as scanner_init
    participant LEX as base_yylex (Lexer)
    participant PARSE as base_yyparse (Parser)
    participant SF as scanner_finish

    Client->>Backend: 发送 SQL 文本
    Backend->>PG: PostgresMain() 主循环
    PG->>ESQ: exec_simple_query(sql)
    ESQ->>PPQ: pg_parse_query(sql)

    PPQ->>RP: raw_parser(sql, RAW_PARSE_DEFAULT)
    RP->>SI: scanner_init(sql, keywords)
    SI-->>RP: yyscanner 句柄

    RP->>RP: 设置解析模式（前瞻 Token）
    RP->>RP: parser_init(&yyextra)

    RP->>PARSE: base_yyparse(yyscanner)

    loop 逐 Token 解析
        PARSE->>LEX: base_yylex() 获取下一个 Token
        LEX->>LEX: 扫描输入，识别关键字/标识符/字面量
        LEX-->>PARSE: 返回 Token 类型和值

        PARSE->>PARSE: 根据语法规则移进/规约
        PARSE->>PARSE: 语法动作：构建 AST 节点
    end

    PARSE-->>RP: 返回 yyresult（0=成功，非0=失败）

    RP->>SF: scanner_finish(yyscanner)
    SF-->>RP: 清理完成

    alt 解析成功
        RP-->>PPQ: 返回 List<RawStmt>
        PPQ-->>ESQ: 返回解析树列表
        ESQ->>ESQ: 遍历语句，调用 Analyzer
    else 解析失败
        RP-->>PPQ: 返回 NIL
        PPQ->>PPQ: ereport(ERROR) 报告错误
        PPQ-->>Client: 返回错误消息
    end

/* src/backend/parser/scan.l */
core_yyscan_t
scanner_init(const char *str,
             core_yy_extra_type *yyext,
             const ScanKeywordList *keywordlist,
             const uint16 *keyword_tokens)
{
    Size slen = strlen(str);

    /* 1. 分配扫描器状态结构 */
    yyscan_t scanner;
    yylex_init(&scanner);

    /* 2. 设置输入缓冲区 */
    yy_scan_string(str, scanner);

    /* 3. 关联扩展数据 */
    yyext->keywords = keywordlist;
    yyext->keyword_tokens = keyword_tokens;
    yyext->backslash_quote = backslash_quote;
    yyext->escape_string_warning = escape_string_warning;
    yyext->standard_conforming_strings = standard_conforming_strings;
    yyset_extra(yyext, scanner);

    /* 4. 初始化位置跟踪 */
    yyext->scanbuflen = slen;
    yyext->scanbuf = str;

    return scanner;
}

/* src/backend/parser/parser.c */
int
base_yylex(YYSTYPE *lvalp, YYLTYPE *llocp, core_yyscan_t yyscanner)
{
    base_yy_extra_type *yyextra = pg_yyget_extra(yyscanner);
    int cur_token;
    int next_token;

    /* 1. 处理前瞻 Token（用于模式切换） */
    if (yyextra->have_lookahead)
    {
        yyextra->have_lookahead = false;
        cur_token = yyextra->lookahead_token;
        *llocp = yyextra->lookahead_yylloc;
        if (yyextra->lookahead_end)
            *(yyextra->lookahead_end) = yyextra->lookahead_yyleng;
        return cur_token;
    }

    /* 2. 调用 Flex 生成的 Lexer 获取下一个 Token */
    cur_token = core_yylex(&(lvalp->core_yystype), llocp, yyscanner);

    /* 3. Token 合并逻辑：处理多词关键字 */
    /*
     * 例如：NULLS FIRST 需要合并为 NULLS_FIRST，因为 LALR(1) 仅支持单 Token 前瞻
     */
    if (cur_token == NULLS_LA)  /* NULLS 后可能跟 FIRST/LAST */
    {
        next_token = core_yylex(&(lvalp->core_yystype), llocp, yyscanner);
        if (next_token == FIRST_P)
            cur_token = NULLS_FIRST;
        else if (next_token == LAST_P)
            cur_token = NULLS_LAST;
        else
        {
            /* 不匹配，回退 next_token */
            yyextra->have_lookahead = true;
            yyextra->lookahead_token = next_token;
            yyextra->lookahead_yylloc = *llocp;
        }
    }
    /* （此处省略其他多词关键字处理） */

    return cur_token;
}

/* src/backend/parser/gram.y */

/* 简化的 SELECT 语句规则 */
SelectStmt:
    simple_select
    | select_with_parens
    | select_clause sort_clause opt_for_locking_clause opt_select_limit
    /* ... 其他变体 ... */
    ;

simple_select:
    SELECT opt_all_clause opt_target_list
    into_clause from_clause where_clause
    group_clause having_clause window_clause
    {
        /* 语义动作：构造 SelectStmt 节点 */
        SelectStmt *n = makeNode(SelectStmt);
        n->targetList = $3;          /* 选择列表 */
        n->intoClause = $4;          /* INTO 子句 */
        n->fromClause = $5;          /* FROM 子句 */
        n->whereClause = $6;         /* WHERE 条件 */
        n->groupClause = $7;         /* GROUP BY */
        n->havingClause = $8;        /* HAVING */
        n->windowClause = $9;        /* WINDOW */
        $$ = (Node *) n;
    }
    ;

opt_target_list:
    target_list                      { $$ = $1; }
    | /* EMPTY */                    { $$ = NIL; }
    ;

target_list:
    target_el                        { $$ = list_make1($1); }
    | target_list ',' target_el      { $$ = lappend($1, $3); }
    ;

target_el:
    a_expr AS ColLabel
    {
        /* 构造 ResTarget 节点（带别名） */
        $$ = makeNode(ResTarget);
        $$->name = $3;
        $$->val = (Node *) $1;
        $$->location = @1;
    }
    | a_expr
    {
        /* 构造 ResTarget 节点（无别名） */
        $$ = makeNode(ResTarget);
        $$->name = NULL;
        $$->val = (Node *) $1;
        $$->location = @1;
    }
    | '*'
    {
        /* 通配符 SELECT * */
        ColumnRef *cr = makeNode(ColumnRef);
        cr->fields = list_make1(makeNode(A_Star));
        cr->location = @1;

        $$ = makeNode(ResTarget);
        $$->name = NULL;
        $$->val = (Node *) cr;
        $$->location = @1;
    }
    ;

SelectStmt
├── targetList = List [
│   ├── ResTarget { name=NULL, val=ColumnRef('id'), location=7 }
│   ├── ResTarget { name='user_name', val=ColumnRef('name'), location=11 }
│   ]
├── fromClause = List [
│   └── RangeVar { relname='users', location=33 }
│   ]
├── whereClause = A_Expr {
│   kind = AEXPR_OP,
│   name = List ['='],
│   lexpr = ColumnRef('id'),
│   rexpr = A_Const { val=1, location=49 }
│   }
├── groupClause = NIL
├── havingClause = NULL
└── windowClause = NIL

/* src/backend/parser/gram.y */
void
parser_init(base_yy_extra_type *yyext)
{
    /* 初始化解析树列表为空 */
    yyext->parsetree = NIL;

    /* 初始化错误标志 */
    yyext->have_error = false;
}

/* src/backend/parser/gram.c（Bison 生成） */
int
base_yyparse(core_yyscan_t yyscanner)
{
    /* （此处省略大量 Bison 生成的状态机代码） */

    /* 简化的逻辑伪代码 */
    int yystate = 0;  /* 初始状态 */
    int yytoken;

    while (true)
    {
        /* 1. 获取下一个 Token */
        yytoken = base_yylex(&yylval, &yylloc, yyscanner);

        /* 2. 查表决定动作（移进/规约/接受/错误） */
        int action = yytable[yystate][yytoken];

        if (action > 0)  /* 移进 */
        {
            /* 将 Token 压栈，切换状态 */
            push_stack(yytoken, yylval, yylloc);
            yystate = action;
        }
        else if (action < 0)  /* 规约 */
        {
            /* 根据规则号执行规约 */
            int rule = -action;
            execute_rule(rule);  /* 调用语义动作 */

            /* 弹出规则右部的符号，压入规则左部 */
            pop_stack(rule_length[rule]);
            push_stack(rule_lhs[rule], rule_result);

            /* 切换状态（goto 表） */
            yystate = yygoto[stack_top_state][rule_lhs[rule]];
        }
        else if (action == ACCEPT)  /* 接受 */
        {
            return 0;  /* 解析成功 */
        }
        else  /* 错误 */
        {
            yyerror("syntax error");
            return 1;  /* 解析失败 */
        }
    }
}

/* src/backend/parser/gram.y */
static void
yyerror(core_yyscan_t yyscanner, const char *msg)
{
    parser_yyerror(msg);
}

void
parser_yyerror(const char *msg)
{
    const char *query_text = /* 当前 SQL 文本 */;
    int error_location = /* 错误位置 */;

    /* 报告语法错误 */
    ereport(ERROR,
            (errcode(ERRCODE_SYNTAX_ERROR),
             errmsg("%s", msg),
             parser_errposition(error_location)));
}

SELECT FROM users;

ERROR:  syntax error at or near "FROM"
LINE 1: SELECT FROM users;
               ^

SELECT id, name FROM users WHERE id = 1;

const char *sql = "SELECT id, name FROM users WHERE id = 1;";
List *parsetree_list = raw_parser(sql, RAW_PARSE_DEFAULT);

/* 提取第一个语句 */
RawStmt *rawstmt = linitial_node(RawStmt, parsetree_list);
SelectStmt *select = (SelectStmt *) rawstmt->stmt;

/* 访问解析树 */
printf("目标列数: %d\n", list_length(select->targetList));
printf("表名: %s\n", ((RangeVar *) linitial(select->fromClause))->relname);

BEGIN;
INSERT INTO users VALUES (1, 'Alice');
COMMIT;

const char *sql = "BEGIN; INSERT INTO users VALUES (1, 'Alice'); COMMIT;";
List *parsetree_list = raw_parser(sql, RAW_PARSE_DEFAULT);

/* 遍历所有语句 */
ListCell *lc;
foreach(lc, parsetree_list)
{
    RawStmt *rawstmt = lfirst_node(RawStmt, lc);

    switch (nodeTag(rawstmt->stmt))
    {
        case T_TransactionStmt:
            printf("事务控制语句\n");
            break;
        case T_InsertStmt:
            printf("插入语句\n");
            break;
        default:
            printf("其他语句\n");
    }
}

SELECT * FORM users;  /* FROM 拼写错误 */

ERROR:  syntax error at or near "FORM"
LINE 1: SELECT * FORM users;
                 ^

PREPARE get_user AS SELECT * FROM users WHERE id = $1;
EXECUTE get_user(1);
EXECUTE get_user(2);

/* 设置调试标志 */
debug_print_parse = true;

/* 执行查询 */
SELECT * FROM users;

{QUERY
   :commandType 1
   :targetList (
      {TARGETENTRY
         :expr {VAR :varno 1 :varattno 1}
         :resname id
      }
      ...
   )
   ...
}

gdb --args postgres --single -D /path/to/data postgres
(gdb) break raw_parser
(gdb) run
(gdb) next  # 单步执行
(gdb) print yyextra->parsetree  # 查看解析树

SET client_min_messages = DEBUG1;
SELECT * FROM users;

EXPLAIN (ANALYZE, BUFFERS, TIMING ON) SELECT ...;