execsql2 2.17.0__py3-none-any.whl → 2.17.2__py3-none-any.whl

execsql/script/executor.py

@@ -1,22 +1,28 @@
 """AST-based script executor for execsql.
 
-Walks a :class:`~execsql.script.ast.Script` tree and executes each node,
-replacing the flat ``CommandList.run_next()`` loop for scripts parsed via
-the AST parser.
+Walks a :class:`~execsql.script.ast.Script` tree and executes each node.
+This is the only execution engine; the parser produces the tree, this
+module runs it.
 
 Design:
-    - **The executor owns control flow.**  IF conditions, LOOP iteration,
-      and BATCH boundaries are driven by the tree structure — no
-      ``if_stack`` or ``compiling_loop`` needed.
-    - **SQL and metacommands delegate to the existing runtime.**  SQL is
-      executed via the current database connection; metacommands are
-      dispatched through ``ctx.metacommandlist.eval()``.  All 200+
-      metacommand handlers work unchanged.
-    - **Variable substitution** uses the existing ``substitute_vars()``.
-    - **RuntimeContext is passed explicitly** as ``ctx`` — the first
-      module migrated to instance-based context (Phase 2).  The public
-      ``execute()`` function defaults to ``get_context()`` if no ``ctx``
-      is provided, so callers that haven't migrated yet work unchanged.
+    - **Control flow is tree-driven.** IF conditions, LOOP iteration, and
+      BATCH boundaries are resolved by walking nested nodes, not by
+      runtime state flags.
+    - **SQL and metacommands delegate to the existing runtime.** SQL
+      runs against the active database connection; metacommands are
+      dispatched through ``ctx.metacommandlist.eval()`` (the same
+      ~225-entry dispatch table the rest of the codebase uses).
+    - **Variable substitution** uses :func:`execsql.script.engine.substitute_vars`.
+    - **Context is explicit.** :func:`execute` takes a
+      :class:`~execsql.state.RuntimeContext` via the ``ctx`` keyword;
+      when omitted it falls back to :func:`~execsql.state.get_context`.
+      For tracking and error reporting the executor pushes
+      :class:`~execsql.state.ExecFrame` records onto
+      ``ctx.ast_exec_stack`` as it descends into IF / LOOP / BATCH /
+      INCLUDE'd files / ``EXECUTE SCRIPT`` calls. Scope frames
+      (``main``, ``script``) carry the active ``localvars`` and
+      ``paramvals``; block frames cache a ``scope_ref`` to the
+      enclosing scope for O(1) variable lookup.
 
 Usage::
 
@@ -24,12 +30,13 @@ Usage::
     from execsql.script.parser import parse_script
 
     tree = parse_script("pipeline.sql")
-    execute(tree)  # uses global context
+    execute(tree)  # uses the thread-local context
 
     # Or with an explicit context:
-    from execsql.state import RuntimeContext, get_context
-    ctx = get_context()
-    execute(tree, ctx=ctx)
+    from execsql.state import RuntimeContext, active_context
+    ctx = RuntimeContext()
+    with active_context(ctx):
+        execute(tree, ctx=ctx)
 """
 
 from __future__ import annotations
@@ -57,9 +64,9 @@ from execsql.script.ast import (
     SqlBlock,
     SqlStatement,
 )
-from execsql.script.engine import CommandList, set_dynamic_system_vars, set_static_system_vars, substitute_vars
+from execsql.script.engine import set_dynamic_system_vars, set_static_system_vars, substitute_vars
 from execsql.script.variables import SubVarSet
-from execsql.state import RuntimeContext, active_context, get_context, xcmd_test
+from execsql.state import ExecFrame, RuntimeContext, active_context, get_context, xcmd_test
 from execsql.utils.errors import exception_desc, exit_now, stamp_errinfo
 
 __all__ = ["execute"]
@@ -81,18 +88,21 @@ _VARLIKE = re.compile(r"!![$@&~#]?\w+!!", re.I)
 
 
 def _stack_localvars(ctx: RuntimeContext) -> SubVarSet | None:
-    """Build the merged local+param variable overlay from the current stack frame.
+    """Build the merged ``~`` local + ``#`` param overlay for the current scope.
 
-    Returns ``frame.localvars.merge(frame.paramvals)`` for the top frame on
-    ``ctx.commandliststack``, or ``None`` if the stack is empty.  This mirrors
-    the legacy ``CommandList.run_and_increment()`` pattern (line 517 of
-    engine.py) so that both ``substitute_vars`` and ``get_subvarset`` (used by
-    ``x_sub``, ``x_rm_sub``, etc.) operate on the same scope.
+    Returns ``localvars.merge(paramvals)`` for the innermost SCRIPT or
+    ``<main>`` scope frame, or ``None`` if the exec stack is empty.  This is
+    the canonical "current variable scope" used by ``substitute_vars`` and
+    ``get_subvarset`` so that ``x_sub``, ``x_rm_sub``, condition predicates,
+    and prompt handlers all see the same overlay.
     """
-    if ctx.commandliststack:
-        frame = ctx.commandliststack[-1]
-        return frame.localvars.merge(frame.paramvals)
-    return None
+    scope = ctx.current_scope()
+    if scope is None:
+        return None
+    localvars = scope.localvars
+    if localvars is None:
+        return None
+    return localvars.merge(scope.paramvals)
 
 
 def _push_frame(
@@ -102,26 +112,43 @@ def _push_frame(
     line_no: int = 0,
     *,
     paramnames: list[str] | None = None,
-) -> CommandList:
-    """Push a synthetic CommandList frame onto the command-list stack.
-
-    Creates a minimal frame with a sentinel :class:`ScriptCmd` so that
-    ``current_script_line()`` and ``get_subvarset()`` work correctly.
-    Returns the frame so the caller can set ``paramvals`` or pre-populate
-    ``localvars``.
+    kind: str = "script",
+) -> ExecFrame:
+    """Push a scope frame onto the unified AST execution stack.
+
+    Creates an :class:`ExecFrame` of ``kind`` ``"main"`` or ``"script"`` with a
+    fresh :class:`LocalSubVarSet` and the declared ``paramnames``.  Returns
+    the frame so the caller can set ``paramvals`` after parsing the call's
+    arguments.
     """
-    from execsql.script.engine import MetacommandStmt, ScriptCmd
-
-    sentinel = ScriptCmd(source, line_no, "cmd", MetacommandStmt(f"BEGIN SCRIPT {name}"))
-    frame = CommandList([sentinel], name, paramnames)
-    ctx.commandliststack.append(frame)
+    from execsql.script.variables import LocalSubVarSet
+
+    frame = ExecFrame(
+        kind=kind,
+        label=name,
+        source=source,
+        line=line_no or None,
+        localvars=LocalSubVarSet(),
+        paramnames=paramnames,
+    )
+    ctx.ast_exec_stack.append(frame)
     return frame
 
 
 def _pop_frame(ctx: RuntimeContext) -> None:
-    """Pop the top frame from the command-list stack."""
-    if ctx.commandliststack:
-        ctx.commandliststack.pop()
+    """Pop the top scope frame from the AST execution stack."""
+    if ctx.ast_exec_stack:
+        ctx.ast_exec_stack.pop()
+
+
+def _push_block_frame(ctx: RuntimeContext, frame: ExecFrame) -> None:
+    """Push a non-scope frame (if/loop/batch/include) onto the exec stack.
+
+    Caches a reference to the enclosing SCRIPT/main scope on the frame so
+    that ``current_localvars()`` stays O(1) regardless of nesting depth.
+    """
+    frame.scope_ref = ctx.current_scope()
+    ctx.ast_exec_stack.append(frame)
 
 
 def _convert_deferred_vars(text: str) -> str:
@@ -376,12 +403,15 @@ def _execute_node(
         _execute_loop(ctx, node, localvars)
 
     elif isinstance(node, BatchBlock):
+        ctx.last_command = _FakeScriptCmd(node)
         _execute_batch(ctx, node, localvars, in_loop=in_loop)
 
     elif isinstance(node, ScriptBlock):
+        ctx.last_command = _FakeScriptCmd(node)
         _register_script_block(ctx, node)
 
     elif isinstance(node, SqlBlock):
+        ctx.last_command = _FakeScriptCmd(node)
         _execute_sql_block(ctx, node, localvars, in_loop=in_loop)
 
     elif isinstance(node, IncludeDirective):
@@ -407,20 +437,48 @@ def _execute_if(
     *,
     in_loop: bool = False,
 ) -> None:
-    """Evaluate an IF block and execute the matching branch."""
+    """Evaluate an IF block and execute the matching branch.
+
+    Pushes an :class:`ExecFrame` onto ``ctx.ast_exec_stack`` for the active
+    branch while its body executes, so the debug REPL and
+    ``DEBUG WRITE COMMANDLISTSTACK`` see the current IF nesting.
+    """
+    from execsql.state import ExecFrame
+
     if _eval_condition(ctx, node.condition, node.condition_modifiers):
-        _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=in_loop)
+        _push_block_frame(
+            ctx,
+            ExecFrame(kind="if", label=node.condition, source=node.span.file, line=node.span.start_line),
+        )
+        try:
+            _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=in_loop)
+        finally:
+            ctx.ast_exec_stack.pop()
         return
 
     # Try ELSEIF clauses
     for clause in node.elseif_clauses:
         if _eval_condition(ctx, clause.condition, clause.condition_modifiers):
-            _execute_nodes(ctx, clause.body, node.span.file, localvars, in_loop=in_loop)
+            _push_block_frame(
+                ctx,
+                ExecFrame(kind="elseif", label=clause.condition, source=node.span.file, line=node.span.start_line),
+            )
+            try:
+                _execute_nodes(ctx, clause.body, node.span.file, localvars, in_loop=in_loop)
+            finally:
+                ctx.ast_exec_stack.pop()
             return
 
     # ELSE branch
     if node.else_body:
-        _execute_nodes(ctx, node.else_body, node.span.file, localvars, in_loop=in_loop)
+        _push_block_frame(
+            ctx,
+            ExecFrame(kind="else", label="", source=node.span.file, line=node.span.start_line),
+        )
+        try:
+            _execute_nodes(ctx, node.else_body, node.span.file, localvars, in_loop=in_loop)
+        finally:
+            ctx.ast_exec_stack.pop()
 
 
 def _execute_loop(
@@ -429,29 +487,39 @@ def _execute_loop(
     localvars: SubVarSet | None = None,
 ) -> None:
     """Execute a LOOP WHILE or LOOP UNTIL block."""
+    from execsql.state import ExecFrame
+
     # Convert deferred vars in the condition — they re-evaluate each iteration
     condition = _convert_deferred_vars(node.condition)
 
-    if node.loop_type == "WHILE":
-        while True:
-            effective_locals = _stack_localvars(ctx)
-            expanded = substitute_vars(condition, effective_locals, ctx=ctx)
-            if not xcmd_test(expanded):
-                break
-            try:
-                _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=True)
-            except _BreakLoop:
-                break
-    else:  # UNTIL
-        while True:
-            try:
-                _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=True)
-            except _BreakLoop:
-                break
-            effective_locals = _stack_localvars(ctx)
-            expanded = substitute_vars(condition, effective_locals, ctx=ctx)
-            if xcmd_test(expanded):
-                break
+    kind = "loop_while" if node.loop_type == "WHILE" else "loop_until"
+    frame = ExecFrame(kind=kind, label=node.condition, source=node.span.file, line=node.span.start_line, iteration=0)
+    _push_block_frame(ctx, frame)
+    try:
+        if node.loop_type == "WHILE":
+            while True:
+                effective_locals = _stack_localvars(ctx)
+                expanded = substitute_vars(condition, effective_locals, ctx=ctx)
+                if not xcmd_test(expanded):
+                    break
+                frame.iteration += 1
+                try:
+                    _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=True)
+                except _BreakLoop:
+                    break
+        else:  # UNTIL
+            while True:
+                frame.iteration += 1
+                try:
+                    _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=True)
+                except _BreakLoop:
+                    break
+                effective_locals = _stack_localvars(ctx)
+                expanded = substitute_vars(condition, effective_locals, ctx=ctx)
+                if xcmd_test(expanded):
+                    break
+    finally:
+        ctx.ast_exec_stack.pop()
 
 
 def _execute_batch(
@@ -462,10 +530,17 @@ def _execute_batch(
     in_loop: bool = False,
 ) -> None:
     """Execute a BEGIN BATCH / END BATCH block."""
+    from execsql.state import ExecFrame
+
     ctx.status.batch.new_batch()
+    _push_block_frame(
+        ctx,
+        ExecFrame(kind="batch", label="", source=node.span.file, line=node.span.start_line),
+    )
     try:
         _execute_nodes(ctx, node.body, node.span.file, localvars, in_loop=in_loop)
     finally:
+        ctx.ast_exec_stack.pop()
         if ctx.status.batch.in_batch():
             ctx.status.batch.end_batch()
 
@@ -498,135 +573,9 @@ def _pre_register_scripts(ctx: RuntimeContext, nodes: list[Node]) -> None:
 
 
 def _register_script_block(ctx: RuntimeContext, node: ScriptBlock) -> None:
-    """Register a named SCRIPT block.
-
-    Stores the AST node in ``ctx.ast_scripts`` for native execution, and also
-    builds a legacy ``CommandList`` in ``ctx.savedscripts`` so that dispatch
-    table handlers (e.g., ON ERROR_HALT EXECUTE SCRIPT) still work.
-    """
-    from execsql.script.engine import CommandList
-
-    # AST-native registry
+    """Register a named SCRIPT block in the AST script registry."""
     ctx.ast_scripts[node.name] = node
 
-    # Legacy compatibility — flatten to CommandList for dispatch table
-    cmdlist = _flatten_for_legacy(node.body, node.span.file)
-    cl = CommandList(cmdlist, node.name, node.param_names)
-    ctx.savedscripts[node.name] = cl
-
-
-def _flatten_for_legacy(nodes: list[Node], source: str) -> list:
-    """Convert AST nodes to flat ScriptCmd list for legacy compatibility."""
-    from execsql.script.engine import MetacommandStmt, ScriptCmd, SqlStmt
-
-    result = []
-    for node in nodes:
-        if isinstance(node, SqlStatement):
-            text = re.sub(r"\s*;(\s*;\s*)+$", ";", node.text)
-            result.append(
-                ScriptCmd(node.span.file, node.span.start_line, "sql", SqlStmt(text)),
-            )
-        elif isinstance(node, MetaCommandStatement):
-            result.append(
-                ScriptCmd(node.span.file, node.span.start_line, "cmd", MetacommandStmt(node.command)),
-            )
-        elif isinstance(node, IfBlock):
-            result.append(
-                ScriptCmd(
-                    node.span.file,
-                    node.span.start_line,
-                    "cmd",
-                    MetacommandStmt(f"IF ({node.condition})"),
-                ),
-            )
-            # Emit ANDIF/ORIF condition modifiers after the IF
-            for mod in node.condition_modifiers:
-                keyword = "ANDIF" if mod.kind == "AND" else "ORIF"
-                result.append(
-                    ScriptCmd(
-                        mod.span.file,
-                        mod.span.start_line,
-                        "cmd",
-                        MetacommandStmt(f"{keyword} ({mod.condition})"),
-                    ),
-                )
-            result.extend(_flatten_for_legacy(node.body, source))
-            for clause in node.elseif_clauses:
-                result.append(
-                    ScriptCmd(
-                        clause.span.file,
-                        clause.span.start_line,
-                        "cmd",
-                        MetacommandStmt(f"ELSEIF ({clause.condition})"),
-                    ),
-                )
-                result.extend(_flatten_for_legacy(clause.body, source))
-            if node.else_body:
-                result.append(
-                    ScriptCmd(
-                        node.span.file,
-                        node.else_span.start_line if node.else_span else node.span.start_line,
-                        "cmd",
-                        MetacommandStmt("ELSE"),
-                    ),
-                )
-                result.extend(_flatten_for_legacy(node.else_body, source))
-            result.append(
-                ScriptCmd(
-                    node.span.file,
-                    node.span.effective_end_line,
-                    "cmd",
-                    MetacommandStmt("ENDIF"),
-                ),
-            )
-        elif isinstance(node, LoopBlock):
-            result.append(
-                ScriptCmd(
-                    node.span.file,
-                    node.span.start_line,
-                    "cmd",
-                    MetacommandStmt(f"LOOP {node.loop_type} ({node.condition})"),
-                ),
-            )
-            result.extend(_flatten_for_legacy(node.body, source))
-            result.append(
-                ScriptCmd(
-                    node.span.file,
-                    node.span.effective_end_line,
-                    "cmd",
-                    MetacommandStmt("END LOOP"),
-                ),
-            )
-        elif isinstance(node, BatchBlock):
-            result.append(
-                ScriptCmd(node.span.file, node.span.start_line, "cmd", MetacommandStmt("BEGIN BATCH")),
-            )
-            result.extend(_flatten_for_legacy(node.body, source))
-            result.append(
-                ScriptCmd(node.span.file, node.span.effective_end_line, "cmd", MetacommandStmt("END BATCH")),
-            )
-        elif isinstance(node, SqlBlock):
-            result.extend(_flatten_for_legacy(node.body, source))
-        elif isinstance(node, IncludeDirective):
-            if node.is_execute_script:
-                parts = ["EXECUTE SCRIPT"]
-                if node.if_exists:
-                    parts.append("IF EXISTS")
-                parts.append(node.target)
-                if node.arguments:
-                    parts.append(f"WITH ARGS ({node.arguments})")
-                if node.loop_type:
-                    parts.append(f"{node.loop_type} ({node.loop_condition})")
-                result.append(
-                    ScriptCmd(node.span.file, node.span.start_line, "cmd", MetacommandStmt(" ".join(parts))),
-                )
-            else:
-                prefix = "INCLUDE IF EXISTS" if node.if_exists else "INCLUDE"
-                result.append(
-                    ScriptCmd(node.span.file, node.span.start_line, "cmd", MetacommandStmt(f"{prefix} {node.target}")),
-                )
-    return result
-
 
 def _execute_sql_block(
     ctx: RuntimeContext,
@@ -666,22 +615,12 @@ def _execute_include(
             _execute_script_native(ctx, node, ctx.ast_scripts[target], localvars)
             return
 
-        # Target not in AST registry — might be defined in an INCLUDE'd file
-        # that hasn't been loaded yet.  Fall through to legacy dispatch.
-        if not node.if_exists and target not in ctx.savedscripts:
-            raise ErrInfo(
-                "cmd",
-                other_msg=f"There is no SCRIPT named {node.target}.",
-            )
-        if node.if_exists and target not in ctx.savedscripts:
-            return  # IF EXISTS — skip silently
-
-        # Target is in savedscripts but not ast_scripts — this shouldn't
-        # happen when the AST executor is the only engine, but handle it
-        # gracefully by raising an error.
+        # Target not registered — IF EXISTS silently skips; otherwise error.
+        if node.if_exists:
+            return
         raise ErrInfo(
             "cmd",
-            other_msg=f"SCRIPT {node.target} is not registered in the AST executor.",
+            other_msg=f"There is no SCRIPT named {node.target}.",
         )
 
     # --- INCLUDE (file inclusion) — parse and execute natively ---
@@ -696,10 +635,11 @@ def _execute_script_native(
 ) -> None:
     """Execute a SCRIPT block natively through the AST executor.
 
-    Pushes a :class:`CommandList` frame onto ``ctx.commandliststack`` so that
-    legacy metacommand handlers (``x_sub``, ``x_rm_sub``, ``xf_sub_defined``,
-    prompt handlers, etc.) can access ``~`` local variables and ``#`` script
-    arguments via ``get_subvarset()`` / ``commandliststack[-1]``.  The frame
+    Pushes a SCRIPT-kind :class:`~execsql.state.ExecFrame` onto
+    ``ctx.ast_exec_stack`` so that metacommand handlers (``x_sub``,
+    ``x_rm_sub``, ``xf_sub_defined``, prompt handlers, etc.) can access
+    ``~`` local variables and ``#`` script arguments via
+    ``ctx.current_localvars()`` / ``ctx.current_paramvals()``. The frame
     is popped on exit (including on error) via ``try/finally``.
     """
     from execsql.script.variables import ScriptArgSubVarSet
@@ -754,7 +694,7 @@ def _execute_script_native(
                 if pdef.default is not None:
                     paramvals.add_substitution(f"#{pdef.name}", pdef.default)
 
-    # Push a CommandList frame onto the stack so that:
+    # Push a SCRIPT-kind ExecFrame onto ast_exec_stack so that:
     #   - get_subvarset() can find ~local and +outer-scope variables
     #   - xf_sub_defined/xf_sub_empty can check ~local and #param variables
     #   - current_script_line() returns meaningful source location
@@ -765,9 +705,11 @@ def _execute_script_native(
         script_block.span.file,
         script_block.span.start_line,
         paramnames=script_block.param_names,
+        kind="script",
     )
     if paramvals is not None:
         frame.paramvals = paramvals
+        frame.params = dict(paramvals.substitutions)
 
     try:
 
@@ -787,12 +729,14 @@ def _execute_script_native(
                 expanded = substitute_vars(condition, effective_locals, ctx=ctx)
                 if not xcmd_test(expanded):
                     break
+                frame.iteration += 1
                 try:
                     _run_body()
                 except _BreakLoop:
                     break
         elif node.loop_type == "UNTIL":
             while True:
+                frame.iteration += 1
                 try:
                     _run_body()
                 except _BreakLoop:
@@ -802,7 +746,13 @@ def _execute_script_native(
                 if xcmd_test(expanded):
                     break
         else:
-            _run_body()
+            try:
+                _run_body()
+            except _BreakLoop as exc:
+                raise ErrInfo(
+                    type="cmd",
+                    other_msg=f"BREAK metacommand inside SCRIPT '{script_block.name}' but not inside a LOOP.",
+                ) from exc
     finally:
         _pop_frame(ctx)
 
@@ -867,10 +817,17 @@ def _execute_include_native(
     _pre_register_scripts(ctx, included_tree.body)
 
     # Execute with include-chain tracking
+    from execsql.state import ExecFrame
+
     ctx.include_chain.append(resolved)
+    _push_block_frame(
+        ctx,
+        ExecFrame(kind="include", label=Path(resolved).name, source=resolved, line=1),
+    )
     try:
         _execute_nodes(ctx, included_tree.body, included_tree.source, localvars)
     finally:
+        ctx.ast_exec_stack.pop()
         ctx.include_chain.pop()
 
 
@@ -975,6 +932,8 @@ def execute(script: Script, *, ctx: RuntimeContext | None = None) -> None:
     with active_context(ctx):
         ctx.ast_scripts.clear()
         ctx.include_chain.clear()
+        ctx.ast_exec_stack.clear()
+        ctx.last_command = None
         # Seed the include chain with the main script to catch self-includes.
         if script.source != "<inline>":
             try:
@@ -986,11 +945,11 @@ def execute(script: Script, *, ctx: RuntimeContext | None = None) -> None:
         # The legacy engine registered scripts at parse time (two-pass);
         # the AST executor must do an explicit pre-scan.
         _pre_register_scripts(ctx, script.body)
-        # Push a root frame so commandliststack is never empty during AST
-        # execution.  This ensures get_subvarset(), current_script_line(),
-        # xf_sub_defined(), the REPL, and all other commandliststack readers
-        # work correctly even at the top level.
-        _push_frame(ctx, "<main>", script.source)
+        # Push a root <main> scope frame so the AST exec stack is never
+        # empty during execution.  This ensures get_subvarset(),
+        # current_script_line(), xf_sub_defined(), the REPL, and every
+        # variable-scoping reader works correctly even at the top level.
+        _push_frame(ctx, "<main>", script.source, line_no=1, kind="main")
         try:
             _execute_nodes(ctx, script.body, script.source)
         except _BreakLoop as exc:

execsql/script/parser.py

@@ -1,9 +1,7 @@
 """AST-producing parser for execsql scripts.
 
 Converts raw ``.sql`` script text into a :class:`~execsql.script.ast.Script`
-tree.  This is intended to eventually replace ``_parse_script_lines()`` in
-:mod:`execsql.script.engine` — during the transition both paths coexist and
-can be compared for correctness.
+tree consumed by :func:`execsql.script.executor.execute`.
 
 The parser is a single-pass, line-oriented state machine that tracks:
 

execsql/script/variables.py

@@ -248,8 +248,12 @@ class SubVarSet:
                     sub = sub.replace("\\", "\\\\")
                 quote = m.group("q")
                 if quote == "'":
-                    sub = sub.replace("'", "''")
+                    # Wrap value in single quotes, doubling any embedded
+                    # apostrophe — produces a SQL string literal.
+                    sub = "'" + sub.replace("'", "''") + "'"
                 elif quote == '"':
+                    # Wrap value in double quotes — produces a SQL quoted
+                    # identifier or quoted metacommand argument.
                     sub = '"' + sub + '"'
                 return command_str[: m.start()] + sub + command_str[m.end() :], True
             # Token found but variable not defined — skip it and keep searching.
@@ -277,12 +281,13 @@ class SubVarSet:
             idx = cmd_lower.find(token)
             if idx != -1:
                 return command_str[:idx] + sub + command_str[idx + len(token) :], True
-            # Single-quote-escaped token: !'!varname!'!
+            # Single-quote-wrapped token: !'!varname!'!
             tokenq = f"!'!{varname}!'!"
             idxq = cmd_lower.find(tokenq)
             if idxq != -1:
+                wrapped = "'" + sub.replace("'", "''") + "'"
                 return (
-                    command_str[:idxq] + sub.replace("'", "''") + command_str[idxq + len(tokenq) :],
+                    command_str[:idxq] + wrapped + command_str[idxq + len(tokenq) :],
                     True,
                 )
             # Double-quote-wrapped token: !"!varname!"!