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

execsql/gui/desktop.py

@@ -849,7 +849,7 @@ class ActionDialog:
 
 
 # ---------------------------------------------------------------------------
-# MapDialog — shows tabular data (no interactive map without tkintermapview)
+# MapDialog — interactive map via tkintermapview (tabular fallback if missing)
 # ---------------------------------------------------------------------------
 
 
@@ -870,22 +870,31 @@ class MapDialog:
                 anchor="w",
                 pady=(0, 4),
             )
-        ttk.Label(frame, text="(Interactive map requires tkintermapview; showing tabular data)").pack(
-            anchor="w",
-            pady=(0, 8),
-        )
 
         headers = args.get("headers", [])
         rows = args.get("rows", [])
-        if headers and rows:
-            tree_frame = ttk.Frame(frame)
-            tree_frame.pack(fill=tk.BOTH, expand=True)
-            tree = ttk.Treeview(tree_frame, height=min(12, len(rows)))
-            _populate_treeview(tree, headers, rows)
-            vsb = ttk.Scrollbar(tree_frame, orient=tk.VERTICAL, command=tree.yview)
-            tree.configure(yscrollcommand=vsb.set)
-            tree.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
-            vsb.pack(side=tk.RIGHT, fill=tk.Y)
+        rendered_map = self._try_render_map(frame, args, headers, rows)
+        if not rendered_map:
+            ttk.Label(
+                frame,
+                text=(
+                    "(Interactive map requires the tkintermapview package — "
+                    "`pip install execsql2[map]` — showing tabular data)"
+                ),
+                wraplength=580,
+                justify="left",
+            ).pack(anchor="w", pady=(0, 8))
+            if headers and rows:
+                tree_frame = ttk.Frame(frame)
+                tree_frame.pack(fill=tk.BOTH, expand=True)
+                tree = ttk.Treeview(tree_frame, height=min(12, len(rows)))
+                _populate_treeview(tree, headers, rows)
+                vsb = ttk.Scrollbar(tree_frame, orient=tk.VERTICAL, command=tree.yview)
+                tree.configure(yscrollcommand=vsb.set)
+                tree.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
+                vsb.pack(side=tk.RIGHT, fill=tk.Y)
+
+        if rows:
             ttk.Label(frame, text=_row_count_text(len(rows))).pack(anchor="w")
 
         button_list = args.get("button_list", [("Continue", 1, "<Return>")])
@@ -893,15 +902,120 @@ class MapDialog:
         btn_frame.pack(pady=8, anchor="e")
         _add_buttons(btn_frame, button_list, lambda v: self._close(win, v))
 
-        _center_window(win, 600, 450)
+        _center_window(win, 750, 600)
         root.wait_window(win)
 
+    def _try_render_map(self, frame: ttk.Frame, args: dict, headers: list, rows: list) -> bool:
+        import warnings
+
+        # tkintermapview pulls in `geocoder`, which has a Python 3.12+ SyntaxWarning
+        # from an unescaped \d in a regex string literal. It's harmless but noisy.
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=SyntaxWarning, module=r"geocoder.*")
+            try:
+                from tkintermapview import TkinterMapView
+            except ImportError:
+                return False
+
+        lat_col = args.get("lat_col")
+        lon_col = args.get("lon_col")
+        if not (lat_col and lon_col and headers and rows):
+            return False
+
+        hdrs_lower = [str(h).lower() for h in headers]
+
+        def _idx(col: str | None) -> int | None:
+            if not col:
+                return None
+            try:
+                return hdrs_lower.index(col.lower())
+            except ValueError:
+                return None
+
+        lat_idx = _idx(lat_col)
+        lon_idx = _idx(lon_col)
+        if lat_idx is None or lon_idx is None:
+            return False
+
+        label_idx = _idx(args.get("label_col"))
+        color_idx = _idx(args.get("color_col"))
+
+        markers: list[tuple[float, float, str | None, str | None]] = []
+        for row in rows:
+            try:
+                lat = float(row[lat_idx])
+                lon = float(row[lon_idx])
+            except (TypeError, ValueError, IndexError):
+                continue
+            label = str(row[label_idx]) if label_idx is not None and row[label_idx] is not None else None
+            color = str(row[color_idx]) if color_idx is not None and row[color_idx] is not None else None
+            markers.append((lat, lon, label, color))
+
+        if not markers:
+            return False
+
+        try:
+            map_widget = TkinterMapView(frame, width=700, height=480, corner_radius=0)
+        except Exception:
+            # Headless display, no Tk root, or any other map-widget failure —
+            # fall back to tabular rather than crashing the dialog.
+            return False
+        map_widget.pack(fill=tk.BOTH, expand=True, pady=(0, 8))
+        # Force the geometry manager to assign the real packed size to the widget
+        # so its tile-box math uses the actual on-screen dimensions, not the
+        # constructor values. Without this the first paint can fetch tiles for
+        # the wrong viewport and the basemap appears blank.
+        map_widget.update_idletasks()
+
+        avg_lat = sum(m[0] for m in markers) / len(markers)
+        avg_lon = sum(m[1] for m in markers) / len(markers)
+        zoom = _pick_zoom(markers)
+
+        def _populate() -> None:
+            map_widget.set_position(avg_lat, avg_lon)
+            map_widget.set_zoom(zoom)
+            for lat, lon, label, color in markers:
+                kwargs: dict = {}
+                if label:
+                    kwargs["text"] = label
+                # Setting only `marker_color_circle` (not `marker_color_outside`)
+                # renders a small colored dot instead of the chunky full drop-pin.
+                if color:
+                    kwargs["marker_color_circle"] = color
+                map_widget.set_marker(lat, lon, **kwargs)
+
+        # Defer marker / position setup until after the widget's first <Configure>
+        # event so tile loading happens against the realized dimensions.
+        map_widget.after_idle(_populate)
+        return True
+
     def _close(self, win: tk.Toplevel, value: int | None) -> None:
         self.result = {"button": value}
         if win.winfo_exists():
             win.destroy()
 
 
+def _pick_zoom(markers: list[tuple[float, float, str | None, str | None]]) -> int:
+    if len(markers) <= 1:
+        return 10
+    lat_span = max(m[0] for m in markers) - min(m[0] for m in markers)
+    lon_span = max(m[1] for m in markers) - min(m[1] for m in markers)
+    span = max(lat_span, lon_span)
+    if span > 60:
+        return 2
+    if span > 30:
+        return 3
+    if span > 15:
+        return 4
+    if span > 5:
+        return 5
+    if span > 2:
+        return 7
+    if span > 0.5:
+        return 9
+    return 11
+
+
 # ---------------------------------------------------------------------------
 # CredentialsDialog
 # ---------------------------------------------------------------------------

execsql/importers/__init__.py

@@ -5,5 +5,5 @@ Importer package for execsql.
 
 Each sub-module reads a specific file format and loads data into a target
 database table via the active :class:`~execsql.db.base.Database` connection.
-Sub-modules: ``base``, ``csv``, ``ods``, ``xls``, ``feather``.
+Sub-modules: ``base``, ``csv``, ``json``, ``ods``, ``xls``, ``feather``.
 """

execsql/importers/ods.py

@@ -6,7 +6,7 @@ ODS spreadsheet import for execsql.
 Provides :func:`ods_data` (row iterator over an ODS sheet) and
 :func:`importods` (imports an ODS sheet into a database table), used by
 the ``IMPORT … FORMAT ods`` metacommand.  Requires ``odfpy``
-(``execsql2[ods]``).
+(``execsql2[formats]``).
 """
 
 from typing import Any

execsql/importers/xls.py

@@ -6,7 +6,7 @@ XLS and XLSX spreadsheet import for execsql.
 Provides :func:`xls_data` / :func:`importxls` (``xlrd``-based ``.xls``
 reader) and the XLSX equivalent using ``openpyxl``.  Used by
 ``IMPORT … FORMAT xls`` and ``FORMAT xlsx``.  Requires
-``execsql2[excel]``.
+``execsql2[formats]``.
 """
 
 from typing import Any

execsql/metacommands/__init__.py

@@ -1,11 +1,40 @@
 """execsql metacommand dispatch table.
 
-Importing this module populates a MetaCommandList (``DISPATCH_TABLE``) with
-every metacommand regex and its handler function.  The dispatch table is
-consumed by script.MetacommandStmt.run() via ``_state.metacommandlist``.
+Importing this module populates a ``MetaCommandList`` (``DISPATCH_TABLE``)
+with every metacommand regex and its handler function. The dispatch
+table is consumed by ``script.MetacommandStmt.run()`` via
+``_state.metacommandlist``.
 
-Handler functions live in the sibling modules:
-  connect, conditions, control, data, debug, io, prompt, script_ext, system
+The table itself is built by ``build_dispatch_table()`` in
+:mod:`execsql.metacommands.dispatch`. Handler functions are organized
+into sibling modules by topic:
+
+- :mod:`~execsql.metacommands.connect` — CONNECT / USE / DISCONNECT
+  / AUTOCOMMIT / PG_VACUUM.
+- :mod:`~execsql.metacommands.conditions` — ``xf_*`` predicates used
+  by IF / ELSEIF / ASSERT.
+- :mod:`~execsql.metacommands.control` — IF / ELSEIF / ELSE / ENDIF /
+  ANDIF / ORIF, ASSERT, LOOP, BATCH, HALT, BREAK, WAIT_UNTIL,
+  error-halt directives.
+- :mod:`~execsql.metacommands.data` — SUB family, counters, IMPORT
+  config metacommands.
+- :mod:`~execsql.metacommands.debug` — DEBUG WRITE/LOG variants and
+  SHOW SCRIPTS.
+- :mod:`~execsql.metacommands.io_export` — EXPORT and EXPORT QUERY.
+- :mod:`~execsql.metacommands.io_import` — IMPORT and IMPORT_FILE.
+- :mod:`~execsql.metacommands.io_write` — WRITE, WRITE SCRIPT,
+  WRITE CREATE_TABLE.
+- :mod:`~execsql.metacommands.io_fileops` — INCLUDE, COPY, ZIP,
+  RM_FILE, CD, SERVE.
+- :mod:`~execsql.metacommands.io` — re-export façade for the four
+  ``io_*`` modules above (kept for backward-compatible import paths).
+- :mod:`~execsql.metacommands.prompt` — PROMPT family, ASK, PAUSE.
+- :mod:`~execsql.metacommands.script_ext` — EXECUTE SCRIPT, RUN
+  SCRIPT, EXTEND SCRIPT.
+- :mod:`~execsql.metacommands.system` — SYSTEM_CMD, LOG, EMAIL,
+  CONSOLE, ON ERROR_HALT / ON CANCEL_HALT directives, TIMER.
+- :mod:`~execsql.metacommands.upsert` — PG_UPSERT (optional, requires
+  ``execsql2[upsert]``).
 """
 
 from __future__ import annotations

execsql/metacommands/conditions.py

@@ -3,14 +3,26 @@ from __future__ import annotations
 """
 Conditional test handler functions for execsql.
 
-Implements all ``xf_*`` functions — the conditional test predicates used
-by IF/ELSEIF expressions — and the ``x_if``, ``x_elseif``, ``x_else``,
-and ``x_endif`` imperative handlers that manage the IF-nesting stack.
-
-Examples of conditional tests defined here: ``xf_tableexists``,
-``xf_fileexists``, ``xf_equals``, ``xf_contains``, ``xf_startswith``,
-``xf_greaterthan``, etc., along with all their quoting variants generated
-at registration time.
+Implements the ``xf_*`` predicates used by IF / ELSEIF / ANDIF / ORIF
+/ ASSERT / WAIT_UNTIL expressions. The IF-nesting *imperative*
+handlers (``x_if``, ``x_if_elseif``, ``x_if_else``, ``x_if_end``,
+etc.) live in :mod:`execsql.metacommands.control`.
+
+Predicates registered here (with regex variants generated at
+registration time for quoted, unquoted, and bracketed arguments):
+
+- Object existence: ``xf_fileexists``, ``xf_direxists``,
+  ``xf_schemaexists``, ``xf_tableexists``, ``xf_roleexists``,
+  ``xf_script_exists``, ``xf_sub_defined``.
+- Value tests: ``xf_equals``, ``xf_identical``, ``xf_contains``,
+  ``xf_startswith``, ``xf_endswith``, ``xf_isnull``, ``xf_iszero``,
+  ``xf_istrue``, ``xf_boolliteral``, ``xf_sub_empty``.
+- Numeric comparison: ``xf_isgt``, ``xf_isgte``.
+- Row counts: ``xf_hasrows``, ``xf_row_count_gt``, ``xf_row_count_gte``,
+  ``xf_row_count_eq``, ``xf_row_count_lt``.
+- Runtime state: ``xf_sqlerror``, ``xf_dialogcanceled``, ``xf_dbms``.
+
+The full list is also surfaced by ``execsql --dump-keywords``.
 """
 
 import os
@@ -245,9 +257,9 @@ def xf_sub_defined(**kwargs: Any) -> bool:
     if varname[0] not in ("~", "#"):
         subvarset = _state.subvars
     elif varname[0] == "~":
-        subvarset = _state.commandliststack[-1].localvars
+        subvarset = _state.current_localvars()
     else:
-        subvarset = _state.commandliststack[-1].paramvals
+        subvarset = _state.current_paramvals()
     return subvarset.sub_exists(varname) if subvarset else False
 
 
@@ -256,10 +268,10 @@ def xf_sub_empty(**kwargs: Any) -> bool:
     if varname[0] not in ("~", "#"):
         subvarset = _state.subvars
     elif varname[0] == "~":
-        subvarset = _state.commandliststack[-1].localvars
+        subvarset = _state.current_localvars()
     else:
-        subvarset = _state.commandliststack[-1].paramvals
-    if not subvarset.sub_exists(varname):
+        subvarset = _state.current_paramvals()
+    if subvarset is None or not subvarset.sub_exists(varname):
         raise ErrInfo(
             type="cmd",
             command_text=kwargs["metacommandline"],
@@ -270,7 +282,7 @@ def xf_sub_empty(**kwargs: Any) -> bool:
 
 def xf_script_exists(**kwargs: Any) -> bool:
     script_id = kwargs["script_id"].lower()
-    return script_id in _state.savedscripts
+    return script_id in _state.ast_scripts
 
 
 def xf_equals(**kwargs: Any) -> bool:

execsql/metacommands/connect.py

@@ -3,20 +3,27 @@ from __future__ import annotations
 """
 Database connection metacommand handlers for execsql.
 
-Implements all ``x_connect_*`` handler functions that open or switch
-database connections at script runtime:
-
-- ``x_connect_pg`` — ``CONNECT POSTGRESQL …``
-- ``x_connect_mysql`` — ``CONNECT MYSQL …``
-- ``x_connect_oracle`` — ``CONNECT ORACLE …``
-- ``x_connect_sqlite`` — ``CONNECT SQLITE …``
-- ``x_connect_duckdb`` — ``CONNECT DUCKDB …``
-- ``x_connect_firebird`` — ``CONNECT FIREBIRD …``
-- ``x_connect_sqlserver`` — ``CONNECT SQLSERVER …``
-- ``x_connect_access`` — ``CONNECT ACCESS …``
-- ``x_connect_dsn`` — ``CONNECT DSN …``
-- ``x_use_db`` — ``USE DATABASE <alias>``
-- ``x_close_db`` — ``CLOSE DATABASE <alias>``
+Per-DBMS ``CONNECT`` handlers. Each DBMS has two variants — the bare
+form (credentials taken from regex captures / config) and the
+``_user_`` form (interactive password prompt):
+
+- PostgreSQL: ``x_connect_pg``, ``x_connect_user_pg``
+- SQL Server: ``x_connect_ssvr``, ``x_connect_user_ssvr``
+- MySQL / MariaDB: ``x_connect_mysql``, ``x_connect_user_mysql``
+- Oracle: ``x_connect_ora``, ``x_connect_user_ora``
+- Firebird: ``x_connect_fb``, ``x_connect_user_fb``
+- MS Access: ``x_connect_access``
+- DuckDB: ``x_connect_duckdb``
+- SQLite: ``x_connect_sqlite``
+- ODBC DSN: ``x_connect_dsn``
+
+Plus the connection-management handlers:
+
+- ``x_use`` — ``USE <alias>`` (switch the active database).
+- ``x_disconnect`` — ``DISCONNECT [<alias>]`` (close a registered connection).
+- ``x_autocommit_on`` / ``x_autocommit_off`` — ``AUTOCOMMIT ON|OFF``.
+- ``x_pg_vacuum`` — ``PG_VACUUM`` (run VACUUM against the current Postgres connection).
+- ``x_daoflushdelay`` — ``CONFIG DAO_FLUSH_DELAY_SECS`` (MS Access only).
 """
 
 from pathlib import Path

execsql/metacommands/control.py

@@ -3,17 +3,28 @@ from __future__ import annotations
 """
 Control-flow metacommand handlers for execsql.
 
-Implements the imperative ``x_*`` functions for script flow control:
-
-- Loop management: ``x_loop`` (LOOP … END LOOP), ``x_while_loop``
-  (WHILE … END LOOP), ``x_until_loop`` (UNTIL … END LOOP)
-- Batch control: ``x_begin_batch``, ``x_end_batch``, ``x_commit``,
-  ``x_rollback``
-- Script include/execute: ``x_include``, ``x_execute_script``
-- Named scripts: ``x_begin_script``, ``x_end_script``, ``x_run_script``
-- Error/halt control: ``x_halt``, ``x_on_error``, ``x_on_cancel``
-- Counter operations: ``x_set_counter``, ``x_increment_counter``
-- Substitution variable assignment: ``x_set``
+Implements the ``x_*`` functions for script flow control:
+
+- Conditional execution: ``x_if`` and its companions ``x_if_andif``,
+  ``x_if_orif``, ``x_if_elseif``, ``x_if_else``, ``x_if_end``,
+  ``x_if_block`` (compound IF / ELSEIF / ELSE / ENDIF handling).
+- Assertion: ``x_assert`` (ASSERT condition with optional message).
+- Loop management: ``x_loop`` (LOOP … END LOOP, including WHILE/UNTIL
+  variants matched by the same regex).
+- Batch control: ``x_begin_batch``, ``x_end_batch``, ``x_rollback``.
+- Error/halt control: ``x_halt``, ``x_halt_msg``, ``x_error_halt``,
+  ``x_metacommand_error_halt``.
+- Flow modifiers: ``x_break`` (exit a LOOP), ``x_wait_until``.
+
+Handlers for related areas live in sibling modules:
+
+- INCLUDE / EXECUTE SCRIPT / RUN / named-script registration —
+  :mod:`execsql.metacommands.script_ext` (and the AST executor).
+- Counter operations (RESET COUNTER, SET COUNTER) and substitution
+  variable assignment (SUB, SUB_LOCAL, etc.) —
+  :mod:`execsql.metacommands.data`.
+- ON ERROR_HALT / ON CANCEL_HALT directives —
+  :mod:`execsql.metacommands.system`.
 """
 
 import time
@@ -22,13 +33,8 @@ from execsql.exceptions import ErrInfo
 from typing import Any
 
 import execsql.state as _state
-from execsql.script import (
-    CommandList,
-    MetacommandStmt,
-    ScriptCmd,
-    current_script_line,
-)
-from execsql.utils.errors import exit_now, write_warning
+from execsql.script import current_script_line
+from execsql.utils.errors import exit_now
 from execsql.utils.fileio import EncodedFile, check_dir
 from execsql.utils.gui import GUI_HALT, GuiSpec, enable_gui, gui_console_isrunning
 
@@ -67,67 +73,55 @@ def x_assert(**kwargs: Any) -> None:
         raise ErrInfo(type="assert", other_msg=message)
 
 
+def _ast_only_stub(name: str):
+    """Return an ErrInfo for a metacommand the AST executor handles structurally.
+
+    These handlers stay registered in the dispatch table so ``--dump-keywords``,
+    the VS Code grammar generator, and ``--list-keywords`` still see the
+    keyword.  The AST parser converts the source form (``IF`` / ``ENDIF`` /
+    ``LOOP`` / ``BEGIN BATCH`` / ``BREAK`` / ``ELSE`` / ``ELSEIF`` / ``ANDIF``
+    / ``ORIF``) into structural AST nodes that the executor walks directly —
+    none of these dispatch handlers fire for parsed scripts.  Reaching one
+    means the AST parser failed to recognise the keyword, which is a bug.
+    """
+    from execsql.exceptions import ErrInfo
+
+    return ErrInfo(
+        type="cmd",
+        other_msg=f"{name} should be handled by the AST executor, not the dispatch table.",
+    )
+
+
 def x_if(**kwargs: Any) -> None:
-    tf_value = _state.xcmd_test(kwargs["condtest"])
-    if tf_value:
-        src, line_no = current_script_line()
-        metacmd = MetacommandStmt(kwargs["condcmd"])
-        script_cmd = ScriptCmd(src, line_no, "cmd", metacmd)
-        cmdlist = CommandList([script_cmd], f"{src}_{line_no}")
-        _state.commandliststack.append(cmdlist)
-    return None
+    raise _ast_only_stub("IF")
 
 
 def x_if_orif(**kwargs: Any) -> None:
-    if _state.if_stack.all_true():
-        return None  # Short-circuit evaluation
-    if _state.if_stack.only_current_false():
-        _state.if_stack.replace(_state.xcmd_test(kwargs["condtest"]))
-    return None
+    raise _ast_only_stub("ORIF")
 
 
 def x_if_andif(**kwargs: Any) -> None:
-    if _state.if_stack.all_true():
-        _state.if_stack.replace(_state.if_stack.current() and _state.xcmd_test(kwargs["condtest"]))
-    return None
+    raise _ast_only_stub("ANDIF")
 
 
 def x_if_elseif(**kwargs: Any) -> None:
-    if _state.if_stack.only_current_false():
-        _state.if_stack.replace(_state.xcmd_test(kwargs["condtest"]))
-    else:
-        _state.if_stack.replace(False)
-    return None
+    raise _ast_only_stub("ELSEIF")
 
 
 def x_if_else(**kwargs: Any) -> None:
-    if _state.if_stack.all_true() or _state.if_stack.only_current_false():
-        _state.if_stack.invert()
-    return None
+    raise _ast_only_stub("ELSE")
 
 
 def x_if_block(**kwargs: Any) -> None:
-    if _state.if_stack.all_true():
-        _state.if_stack.nest(_state.xcmd_test(kwargs["condtest"]))
-    else:
-        _state.if_stack.nest(False)
-    return None
+    raise _ast_only_stub("IF")
 
 
 def x_if_end(**kwargs: Any) -> None:
-    _state.if_stack.unnest()
-    return None
+    raise _ast_only_stub("ENDIF")
 
 
 def x_loop(**kwargs: Any) -> None:
-    # LOOP is now handled natively by the AST executor (_execute_loop).
-    # This handler exists only for dispatch table registration compatibility.
-    from execsql.exceptions import ErrInfo
-
-    raise ErrInfo(
-        type="cmd",
-        other_msg="LOOP should be handled by the AST executor, not the dispatch table.",
-    )
+    raise _ast_only_stub("LOOP")
 
 
 def x_halt(**kwargs: Any) -> None:
@@ -186,27 +180,20 @@ def x_metacommand_error_halt(**kwargs: Any) -> None:
 
 
 def x_begin_batch(**kwargs: Any) -> None:
-    _state.status.batch.new_batch()
-    return None
+    raise _ast_only_stub("BEGIN BATCH")
 
 
 def x_end_batch(**kwargs: Any) -> None:
-    _state.status.batch.end_batch()
-    return None
+    raise _ast_only_stub("END BATCH")
 
 
 def x_rollback(**kwargs: Any) -> None:
+    """Roll back all DBs registered in the innermost batch level."""
     _state.status.batch.rollback_batch()
 
 
 def x_break(**kwargs: Any) -> None:
-    if len(_state.commandliststack) == 1:
-        src, line_no = current_script_line()
-        write_warning(f"BREAK metacommand with no command nesting on line {line_no} of {src}")
-    else:
-        _state.if_stack.if_levels = _state.if_stack.if_levels[: _state.commandliststack[-1].init_if_level]
-        _state.commandliststack.pop()
-    return None
+    raise _ast_only_stub("BREAK")
 
 
 def x_wait_until(**kwargs: Any) -> None:

execsql/metacommands/data.py

@@ -2,13 +2,29 @@ from __future__ import annotations
 from execsql.exceptions import ErrInfo
 
 """
-Data import and export metacommand handlers for execsql.
-
-Implements ``x_export`` (the EXPORT metacommand) and ``x_import`` (the
-IMPORT metacommand).  These are among the most complex handlers: they
-parse the full metacommand argument syntax (format, file name, options)
-and delegate to the appropriate exporter or importer function in
-:mod:`execsql.exporters` and :mod:`execsql.importers`.
+Substitution-variable, counter, and IMPORT/EXPORT configuration handlers.
+
+Despite the module name, this file does **not** implement the EXPORT or
+IMPORT metacommands themselves — those live in
+:mod:`execsql.metacommands.io_export` and :mod:`execsql.metacommands.io_import`.
+
+What's actually here:
+
+- Substitution-variable manipulation: ``x_sub``, ``x_sub_local``,
+  ``x_sub_add``, ``x_sub_append``, ``x_sub_empty``, ``x_rm_sub``,
+  ``x_sub_tempfile``, ``x_sub_ini``, ``x_sub_querystring``,
+  ``x_sub_encrypt``, ``x_sub_decrypt``, ``x_subdata``.
+- Data-variable assignment from queries / prompts: ``x_selectsub``,
+  ``x_prompt_selectsub``.
+- Counter operations: ``x_reset_counter``, ``x_reset_counters``,
+  ``x_set_counter``.
+- IMPORT / scanning configuration metacommands (the ``CONFIG …`` form):
+  ``x_empty_strings``, ``x_trim_strings``, ``x_replace_newlines``,
+  ``x_empty_rows``, ``x_only_strings``, ``x_boolean_int``,
+  ``x_boolean_words``, ``x_fold_col_hdrs``, ``x_trim_col_hdrs``,
+  ``x_clean_col_hdrs``, ``x_del_empty_cols``, ``x_create_col_hdrs``,
+  ``x_dedup_col_hdrs``, ``x_import_common_cols_only``, ``x_max_int``.
+- EXPORT configuration: ``x_quote_all_text``.
 """
 
 import math
@@ -54,7 +70,7 @@ def x_sub_empty(**kwargs: Any) -> None:
 
 def x_rm_sub(**kwargs: Any) -> None:
     varname = kwargs["match"]
-    subvarset = _state.subvars if varname[0] != "~" else _state.commandliststack[-1].localvars
+    subvarset = _state.subvars if varname[0] != "~" else _state.current_localvars()
     subvarset.remove_substitution(varname)
     return None
 
@@ -63,7 +79,7 @@ def x_sub_local(**kwargs: Any) -> None:
     varname = kwargs["match"]
     if varname[0] != "~":
         varname = "~" + varname
-    _state.commandliststack[-1].localvars.add_substitution(varname, kwargs["repl"])
+    _state.current_localvars().add_substitution(varname, kwargs["repl"])
     return None