Line data    Source code

       1              : #ifndef BIGQUERY_EMULATOR_BACKEND_ENGINE_SEMANTIC_SCRIPT_SCRIPT_DRIVER_H_
       2              : #define BIGQUERY_EMULATOR_BACKEND_ENGINE_SEMANTIC_SCRIPT_SCRIPT_DRIVER_H_
       3              : 
       4              : // Script-level execution driver.
       5              : //
       6              : // `docs/ENGINE_POLICY.md` describes the local
       7              : // interpreter for BigQuery scripting (`DECLARE`, `SET`, `BEGIN ...
       8              : // END`, `IF`, `WHILE`, `LOOP`, `FOR`, `BREAK`, `CONTINUE`, `RAISE`,
       9              : // `CALL`, `ASSERT`, `EXECUTE IMMEDIATE`, `CREATE PROCEDURE`). Most
      10              : // of those constructs need a place to thread (a) the per-script
      11              : // variable state across statements and (b) the error-handler stack
      12              : // for `EXCEPTION WHEN ERROR THEN ...`. This file is the foundation
      13              : // scaffold for both.
      14              : //
      15              : // What this file owns today (the plan)
      16              : // ------------------------------------------------
      17              : //
      18              : //   * `ScriptDriver` -- the type the rest of the engine reaches
      19              : //     through. The class shape is in place so future families
      20              : //     (DECLARE/SET, BEGIN..END, IF/WHILE/LOOP, EXECUTE IMMEDIATE,
      21              : //     CALL, RAISE/EXCEPTION) can hang their state off it without
      22              : //     re-routing every call site. Today the driver owns a
      23              : //     `semantic::FrameStack` for the variable environment and
      24              : //     exposes the per-statement helpers this package's already-
      25              : //     landed handlers (e.g. ASSERT) need.
      26              : //
      27              : // The variable-environment primitive itself lives in
      28              : // `backend/engine/semantic/frame_stack.h` so the UDF / TVF
      29              : // invocation surface (`docs/ENGINE_POLICY.md`) can reuse
      30              : // the same stack-of-frames type for argument bindings without
      31              : // taking a transitive dependency on the script-statement
      32              : // translation units.
      33              : //
      34              : // What this file does NOT own (deferred per the plan's pragmatic
      35              : // posture)
      36              : // --------
      37              : //
      38              : //   * Statement sequencing for `BEGIN ... END` -- requires
      39              : //     `googlesql/scripting/script_executor.h` (analyzer-level script
      40              : //     parser; the coordinator analyzer is per-statement). Tracked by
      41              : //     `docs/ENGINE_POLICY.md` Family 3.
      42              : //   * `IF` / `WHILE` / `LOOP` / `FOR` / `BREAK` / `CONTINUE` --
      43              : //     Families 4, 6, 11.
      44              : //   * `RAISE` / `EXCEPTION` handlers -- Family 7.
      45              : //   * `EXECUTE IMMEDIATE` -- Family 8.
      46              : //   * `CREATE PROCEDURE` body storage -- Family 9 (storage primitive
      47              : //     missing in `Storage`).
      48              : //   * `CALL` -- Family 10 (depends on Family 9).
      49              : //   * `@@error.message`, `@@last_statement_type`, ... reads on
      50              : //     `ResolvedSystemVariable` -- Family 12.
      51              : //
      52              : // Each deferred family preserves the YAML row at
      53              : // `backend/engine/duckdb/transpiler/node_dispositions.yaml` with
      54              : // `status=planned` so the engine surfaces the structured
      55              : // `notImplemented` envelope rather than silently approximating
      56              : // (the plan's hard rule).
      57              : 
      58              : #include "backend/engine/semantic/frame_stack.h"
      59              : 
      60              : namespace bigquery_emulator {
      61              : namespace backend {
      62              : namespace engine {
      63              : namespace semantic {
      64              : namespace script {
      65              : 
      66              : // Per-script-run driver state. Today the driver only owns the
      67              : // shared `semantic::FrameStack` for the script-level variable
      68              : // environment; future families (error stack, registered procedure
      69              : // bodies, system-variable values) hang off the same object so call
      70              : // sites do not have to re-route.
      71              : //
      72              : // The driver is constructed at the top of a script invocation and
      73              : // destroyed at the bottom. The semantic executor's per-statement
      74              : // handlers receive a (mutable) reference to it via their statement-
      75              : // specific entry points (e.g. `script::ExecuteAssert`).
      76              : class ScriptDriver {
      77              :  public:
      78              :   ScriptDriver();
      79              :   explicit ScriptDriver(FrameStack* external_variables);
      80              :   ~ScriptDriver();
      81              : 
      82              :   ScriptDriver(const ScriptDriver&) = delete;
      83              :   ScriptDriver& operator=(const ScriptDriver&) = delete;
      84              : 
      85            3 :   FrameStack& variables() {
      86            3 :     return external_variables_ != nullptr ? *external_variables_ : variables_;
      87            3 :   }
      88            0 :   const FrameStack& variables() const {
      89            0 :     return external_variables_ != nullptr ? *external_variables_ : variables_;
      90            0 :   }
      91              : 
      92              :  private:
      93              :   FrameStack variables_;
      94              :   FrameStack* external_variables_ = nullptr;
      95              : };
      96              : 
      97              : }  // namespace script
      98              : }  // namespace semantic
      99              : }  // namespace engine
     100              : }  // namespace backend
     101              : }  // namespace bigquery_emulator
     102              : 
     103              : #endif  // BIGQUERY_EMULATOR_BACKEND_ENGINE_SEMANTIC_SCRIPT_SCRIPT_DRIVER_H_