execsql2 2.16.7__tar.gz → 2.16.12__tar.gz

{execsql2-2.16.7 → execsql2-2.16.12}/CHANGELOG.md

@@ -13,6 +13,42 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.16.12] - 2026-05-01
+
+______________________________________________________________________
+
+## [2.16.11] - 2026-05-01
+
+______________________________________________________________________
+
+## [2.16.10] - 2026-05-01
+
+### Fixed
+
+- EXECUTE SCRIPT with a variable-substituted target name (e.g., `EXECUTE SCRIPT !!#script_name!!`) now works correctly. Previously, the parser's regex only accepted literal word characters as the script identifier, causing variable targets to fall through to the dispatch table and fail with "EXECUTE SCRIPT should be handled by the AST executor." The parser now recognizes `!!var!!` substitution patterns as valid script identifiers.
+
+______________________________________________________________________
+
+## [2.16.9] - 2026-05-01
+
+### Added
+
+- `SHOW SCRIPTS` metacommand lists all registered SCRIPT definitions with parameter signatures and source locations.
+- `SHOW SCRIPT <name>` metacommand shows detail for a single SCRIPT (parameters, source file and line range, docstring).
+- `.scripts` REPL command lists all registered scripts; `.scripts <name>` shows detail for one script.
+- Default parameter values for SCRIPT definitions: `BEGIN SCRIPT load(schema, table, batch=1000)`. Parameters with defaults can be omitted at call site; the default value is used automatically. Required parameters must precede optional parameters (like Python).
+- Automatic docstring extraction for SCRIPT blocks. Comments (`--` or `/* */`) immediately following `BEGIN SCRIPT` are captured as documentation. A blank line terminates the docstring. Docstrings are displayed by `SHOW SCRIPT`, `SHOW SCRIPTS`, and `.scripts` in the debug REPL.
+
+______________________________________________________________________
+
+## [2.16.8] - 2026-04-30
+
+### Fixed
+
+- SQL comments (`--` and `/* */`) inside multi-line SQL statements no longer split the statement. Previously, a comment like `-- col2,` between SELECT columns would cause the parser to flush the accumulated SQL at the comment line, sending an incomplete statement to the database. Comments inside SQL are now preserved as part of the statement text.
+
+______________________________________________________________________
+
 ## [2.16.7] - 2026-04-30
 
 ### Fixed

{execsql2-2.16.7 → execsql2-2.16.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: execsql2
-Version: 2.16.7
+Version: 2.16.12
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Homepage, https://execsql2.readthedocs.io
 Project-URL: Repository, https://github.com/geocoug/execsql

{execsql2-2.16.7 → execsql2-2.16.12}/docs/about/divergence.md

@@ -52,6 +52,21 @@ ______________________________________________________________________
 | `CONFIG LOG_SQL`       | Enable SQL query audit logging — writes executed SQL to the log file.                                                                                                                                                                                                                                                                                                                                                    |
 | `PG_UPSERT`            | QA-checked, FK-dependency-ordered upserts from staging to base schema on PostgreSQL. Integrates [pg-upsert](https://pg-upsert.readthedocs.io/) as an optional dependency. Three modes: full pipeline, QA-only, and schema check. Supports `EXPORT_FAILURES`, `EXPORT_FORMAT`, `EXPORT_MAX_ROWS`, and `STRICT_COLUMNS` keywords. `STRICT_COLUMNS` forces all missing columns to be errors (requires `pg-upsert>=1.22.0`). |
 | `IMPORT … FROM JSON`   | Import a JSON file (array of objects or NDJSON) into a database table. Nested objects are flattened with dot-separated column names; arrays are stored as JSON strings.                                                                                                                                                                                                                                                  |
+| `SHOW SCRIPTS`         | List all registered SCRIPT definitions with parameter signatures and source locations. Includes scripts from INCLUDEEd files.                                                                                                                                                                                                                                                                                            |
+| `SHOW SCRIPT <name>`   | Show detail for a single registered SCRIPT: name, parameters (with defaults), source file/line range, and docstring.                                                                                                                                                                                                                                                                                                     |
+
+### SCRIPT Enhancements
+
+| Feature            | Description                                                                                                                                                                                                    |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Default parameters | `BEGIN SCRIPT load(schema, table, batch=1000)` — parameters with defaults can be omitted at call site. Required parameters must precede optional parameters.                                                   |
+| Docstrings         | Comments (`--` or `/* */`) immediately following `BEGIN SCRIPT` are captured as documentation. A blank line terminates the docstring. Displayed by `SHOW SCRIPT`, `SHOW SCRIPTS`, and `.scripts` REPL command. |
+
+### Bug Fixes
+
+| Fix                             | Description                                                                                                                                               |
+| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Variable EXECUTE SCRIPT targets | `EXECUTE SCRIPT !!#var!!` now works — the parser accepts substitution variable patterns as script identifiers, and the executor resolves them at runtime. |
 
 ### Conditional Tests
 
@@ -131,17 +146,19 @@ execsql2 adds a full interactive debugging system that has no equivalent in upst
 
 **REPL commands** (all dot-prefixed to avoid collisions with variable names and SQL):
 
-| Command                | Description                                                               |
-| ---------------------- | ------------------------------------------------------------------------- |
-| `.continue` / `.c`     | Resume normal script execution                                            |
-| `.abort` / `.q`        | Halt the script with exit status 1                                        |
-| `.vars` / `.v`         | List all user, system, local, and counter variables (grouped by type)     |
-| `.vars all` / `.v all` | Include environment variables (`&`) in the listing                        |
-| `.next` / `.n`         | Execute the next statement, then pause again (step mode)                  |
-| `.where` / `.w`        | Show the current script file, line number, and upcoming statement text    |
-| `.stack`               | Show the command-list stack (script name, cursor position, nesting depth) |
-| `.set VAR VAL` / `.s`  | Set or update a substitution variable; prints confirmation on success     |
-| `.help` / `.h`         | Show available commands                                                   |
+| Command                | Description                                                                 |
+| ---------------------- | --------------------------------------------------------------------------- |
+| `.continue` / `.c`     | Resume normal script execution                                              |
+| `.abort` / `.q`        | Halt the script with exit status 1                                          |
+| `.vars` / `.v`         | List all user, system, local, and counter variables (grouped by type)       |
+| `.vars all` / `.v all` | Include environment variables (`&`) in the listing                          |
+| `.next` / `.n`         | Execute the next statement, then pause again (step mode)                    |
+| `.where` / `.w`        | Show the current script file, line number, and upcoming statement text      |
+| `.stack`               | Show the command-list stack (script name, cursor position, nesting depth)   |
+| `.set VAR VAL` / `.s`  | Set or update a substitution variable; prints confirmation on success       |
+| `.scripts`             | List all registered SCRIPT definitions with parameters and source locations |
+| `.scripts NAME`        | Show detail for a specific SCRIPT (parameters, source file/line range)      |
+| `.help` / `.h`         | Show available commands                                                     |
 
 **Non-prefixed input** is interpreted as either a variable lookup or ad-hoc SQL:
 

{execsql2-2.16.7 → execsql2-2.16.12}/docs/reference/metacommands.md

@@ -141,6 +141,8 @@ All REPL commands are dot-prefixed to avoid ambiguity with variable names and SQ
 | `.vars all` | Include environment variables (`&`) in the listing |
 | `.next` or `.n` | Execute the next script statement, then pause again (step mode) |
 | `.stack` | Show the command-list stack: script name, cursor index, and nesting depth |
+| `.scripts` | List all registered SCRIPT definitions with parameters and source locations |
+| `.scripts NAME` | Show detail for a specific SCRIPT (parameters, source file/line range) |
 | `.help` | Show the list of available REPL commands |
 
 **Variable inspection and SQL (no dot prefix):**
@@ -219,6 +221,10 @@ BEGIN SCRIPT <script_name>
 BEGIN SCRIPT <script_name> WITH PARAMETERS (param1[, param2[,..]])
 ```
 
+```
+BEGIN SCRIPT <script_name>(param1, param2=default_value)
+```
+
 ```
 END SCRIPT [script_name]
 ```
@@ -232,6 +238,56 @@ If the WITH PARAMETERS clause is used, the parameter names specified must be ass
 
 The "WITH" and "PARAMETERS" keywords are both optional.
 
+### Default parameter values
+
+Parameters can have default values using `param=value` syntax. Parameters with defaults are optional at the call site — if omitted, the default value is used. Required parameters (no default) must precede optional parameters.
+
+```sql
+-- !x! BEGIN SCRIPT load_data(schema, table, batch_size=1000, dry_run=false)
+INSERT INTO !!#table!! SELECT * FROM staging LIMIT !!#batch_size!!;
+-- !x! END SCRIPT
+
+-- All of these are valid:
+-- !x! EXECUTE SCRIPT load_data(schema=public, table=users)
+-- !x! EXECUTE SCRIPT load_data(schema=public, table=users, batch_size=500)
+-- !x! EXECUTE SCRIPT load_data(schema=public, table=users, batch_size=500, dry_run=true)
+```
+
+A required parameter after an optional parameter is a parse error:
+
+```sql
+-- Parse error: required parameter 'table' after optional parameter 'batch'
+-- !x! BEGIN SCRIPT bad(schema, batch=1000, table)
+```
+
+### Docstrings
+
+Comments (`--` or `/* */`) immediately following the BEGIN SCRIPT line are captured as the script's docstring. A blank line terminates the docstring. Docstrings are displayed by [SHOW SCRIPT](#show_script), [SHOW SCRIPTS](#show_scripts), and the `.scripts` REPL command.
+
+```sql
+-- !x! BEGIN SCRIPT load_data(schema, table)
+-- Load data from staging into the target table.
+-- Parameters:
+--   schema - Target schema name
+--   table  - Target table name
+
+-- !x! SUB ~batch 1000
+INSERT INTO !!#table!! SELECT * FROM staging;
+-- !x! END SCRIPT
+```
+
+Block comments are also valid:
+
+```sql
+-- !x! BEGIN SCRIPT load_data(schema, table)
+/* Load data from staging into the target table. */
+
+INSERT INTO !!#table!! SELECT * FROM staging;
+-- !x! END SCRIPT
+```
+
+### Other notes
+
 If a script name is provided with the END SCRIPT metacommand, it must match the name used in the corresponding BEGIN SCRIPT metacommand. If it does not, *execsql* will halt with an error message.
 
 A BEGIN/END SCRIPT block can be used in ways similar to a separate script file that is included with the [INCLUDE](#include) metacommand. Both allow the same code to be executed repeatedly, either at different locations in the main script or recursively to perform looping.
@@ -2697,6 +2753,61 @@ Assigns the value of the specified numeric expression to the counter. The next t
 The numeric expression may consist of the simple algebraic operations of addition, subtraction, multiplication, and division. Parentheses may be used to control evaluation order. Numeric values used in the expression may be integers or floating-point numbers, but the result will be reduced to an integer before assignment to the counter variable.
 
 
+## SHOW SCRIPTS { #show_scripts }
+
+```
+SHOW SCRIPTS
+```
+
+Lists all registered SCRIPT definitions with their parameter signatures and source locations. This is useful for discovering what scripts are available at runtime, especially when scripts are loaded from INCLUDEEd files whose paths are determined dynamically.
+
+**Example output:**
+
+```
+Registered scripts (3):
+
+  load_data(schema, table, batch_size=1000)    pipeline.sql:15-42
+  cleanup()                                    init.sql:10-25
+  validate(schema, table)                      pipeline.sql:62-80
+```
+
+Default parameter values are shown in the signature. Use `SHOW SCRIPT <name>` for full detail including docstrings.
+
+If no scripts are registered, prints `No scripts registered.`
+
+## SHOW SCRIPT { #show_script }
+
+```
+SHOW SCRIPT <name>
+```
+
+Shows detail for a single registered SCRIPT definition, including its parameter list (with required/optional status and defaults), source file/line range, and docstring.
+
+**Example:**
+
+```sql
+-- !x! SHOW SCRIPT load_data
+```
+
+**Example output:**
+
+```
+Script: load_data(schema, table, batch_size=1000)
+Source: pipeline.sql:15-42
+Parameters:
+  schema      (required)
+  table       (required)
+  batch_size  (optional, default: 1000)
+
+Load data from staging into the target table.
+```
+
+If the script is not found, prints `No script named '<name>' is registered.`
+
+!!! tip
+    In the debug REPL, use `.scripts` to list all scripts or `.scripts <name>` to show detail for one script.
+
+
 ## SUB { #subcmd }
 
 ```

{execsql2-2.16.7 → execsql2-2.16.12}/extras/vscode-execsql/syntaxes/execsql.tmLanguage.json

@@ -93,7 +93,7 @@
     },
     "action-keywords": {
       "comment": "sub, write, execute script, export, etc.",
-      "match": "(?i)\\b(reset\\s+dialog_canceled|write\\s+create_table|export_metadata|pg_upsert\\s+check|sub_querystring|execute\\s+script|append\\s+script|extend\\s+script|reset\\s+counter|export\\s+query|pg_upsert\\s+qa|sub_tempfile|write\\s+script|import_file|set\\s+counter|sub_decrypt|sub_encrypt|autocommit|breakpoint|copy\\s+query|disconnect|select_sub|sub_append|system_cmd|pg_upsert|pg_vacuum|sub_empty|sub_local|connect|include|max_int|rm_file|subdata|sub_add|sub_ini|assert|export|import|rm_sub|debug|email|serve|write|copy|log|run|sub|use|zip|cd)\\b",
+      "match": "(?i)\\b(reset\\s+dialog_canceled|write\\s+create_table|export_metadata|pg_upsert\\s+check|sub_querystring|execute\\s+script|append\\s+script|extend\\s+script|reset\\s+counter|export\\s+query|pg_upsert\\s+qa|show\\s+scripts|sub_tempfile|write\\s+script|import_file|set\\s+counter|show\\s+script|sub_decrypt|sub_encrypt|autocommit|breakpoint|copy\\s+query|disconnect|select_sub|sub_append|system_cmd|pg_upsert|pg_vacuum|sub_empty|sub_local|connect|include|max_int|rm_file|subdata|sub_add|sub_ini|assert|export|import|rm_sub|debug|email|serve|write|copy|log|run|sub|use|zip|cd)\\b",
       "name": "keyword.other.execsql"
     },
     "config-event-keywords": {

{execsql2-2.16.7 → execsql2-2.16.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execsql2"
-version = "2.16.7"
+version = "2.16.12"
 description = "Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE.txt" }
@@ -165,7 +165,7 @@ skip-magic-trailing-comma = false
 line-ending = "auto"
 
 [tool.bumpversion]
-current_version = "2.16.7"
+current_version = "2.16.12"
 commit = true
 tag = true
 tag_name = "v{new_version}"
@@ -188,7 +188,7 @@ addopts = [
     "--cov=execsql",
     "--cov-branch",
     "--cov-report=xml",
-    "--cov-fail-under=90",
+    "--cov-fail-under=89",
     "--strict-markers",
     "--strict-config",
     "--color=yes",

{execsql2-2.16.7 → execsql2-2.16.12}/src/execsql/debug/repl.py

@@ -111,6 +111,8 @@ _HELP_COMMANDS = [
     (".where", ".w", "Show the current script location and upcoming statement"),
     (".stack", "", "Show the command-list stack (script name, line, depth)"),
     (".set VAR VAL", ".s", "Set or update a substitution variable"),
+    (".scripts", "", "List all registered SCRIPT definitions"),
+    (".scripts NAME", "", "Show detail for a specific SCRIPT"),
     (".help", ".h", "Show this help text"),
 ]
 
@@ -290,6 +292,12 @@ def _handle_dot_command(line: str) -> None:
             varname = parts[0]
             value = parts[1] if len(parts) > 1 else ""
             _set_var(varname, value)
+    elif cmd.startswith("scripts"):
+        rest = cmd[7:].strip()
+        if rest:
+            _print_script_detail(rest)
+        else:
+            _print_scripts()
     else:
         _write(f"  {_c(_RED, 'Unknown command:')} {line!r}. Type '.help' for available commands.\n")
 
@@ -507,3 +515,54 @@ def _set_var(varname: str, value: str) -> None:
     else:
         subvars.add_substitution(varname, value)
     _write(f"  {_c(_CYAN, varname)} {_c(_DIM, '=')} {value}\n")
+
+
+def _print_scripts() -> None:
+    """Print all registered SCRIPT definitions."""
+    from execsql.metacommands.debug import _format_script_signature, _format_script_source
+
+    scripts = _state.ast_scripts
+    if not scripts:
+        _write("  (no scripts registered)\n\n")
+        return
+    _write_rule(f" {_c(_BOLD + _YELLOW, 'Scripts')} {_c(_DIM, f'({len(scripts)})')} ")
+    sigs = {name: _format_script_signature(name, block.param_defs) for name, block in scripts.items()}
+    max_sig = max(len(s) for s in sigs.values())
+    for name, block in scripts.items():
+        sig = sigs[name]
+        src = _format_script_source(block.span)
+        _write(f"  {_c(_CYAN, sig):<{max_sig + len(_CYAN) + len(_RESET)}}  {_c(_DIM, src)}\n")
+    _write("\n")
+
+
+def _print_script_detail(name: str) -> None:
+    """Print detail for a single SCRIPT definition."""
+    from execsql.metacommands.debug import _format_script_signature, _format_script_source
+
+    script_name = name.lower()
+    scripts = _state.ast_scripts
+    if script_name not in scripts:
+        _write(f"  {_c(_RED, 'No script named')} {_c(_CYAN, repr(script_name))} {_c(_RED, 'is registered.')}\n")
+        return
+    block = scripts[script_name]
+    sig = _format_script_signature(block.name, block.param_defs)
+    src = _format_script_source(block.span)
+    _write_rule(f" {_c(_BOLD + _YELLOW, 'Script')} {_c(_DIM, '──')} {_c(_CYAN, sig)} ")
+    _write(f"  {_c(_BOLD, 'Source:')}     {src}\n")
+    if block.param_defs:
+        _write(f"  {_c(_BOLD, 'Parameters:')}\n")
+        max_name = max(len(p.name) for p in block.param_defs)
+        for p in block.param_defs:
+            if p.default is not None:
+                _write(
+                    f"    {_c(_CYAN, p.name):<{max_name + len(_CYAN) + len(_RESET)}}  {_c(_DIM, f'(optional, default: {p.default})')}\n",
+                )
+            else:
+                _write(f"    {_c(_CYAN, p.name):<{max_name + len(_CYAN) + len(_RESET)}}  {_c(_DIM, '(required)')}\n")
+    else:
+        _write(f"  {_c(_BOLD, 'Parameters:')} (none)\n")
+    if block.doc:
+        _write("\n")
+        for doc_line in block.doc.split("\n"):
+            _write(f"  {_c(_DIM, doc_line)}\n")
+    _write("\n")

{execsql2-2.16.7 → execsql2-2.16.12}/src/execsql/format.py

@@ -73,6 +73,8 @@ MULTIWORD_KEYWORDS = [
     "PROMPT ASK",
     "WITH TEMPLATE",
     "IN ZIPFILE",
+    "SHOW SCRIPTS",
+    "SHOW SCRIPT",
 ]
 
 # Depth-tracking sets

{execsql2-2.16.7 → execsql2-2.16.12}/src/execsql/metacommands/debug.py

@@ -1,5 +1,4 @@
 from __future__ import annotations
-from execsql.utils.errors import fatal_error
 
 """
 Debug metacommand handlers for execsql.
@@ -7,11 +6,16 @@ Debug metacommand handlers for execsql.
 Provides ``x_debug_write_metacommands``, which implements the
 ``WRITE METACOMMANDS`` debug metacommand that prints the full registered
 metacommand list to the log/console for troubleshooting.
+
+Also provides ``x_show_scripts`` and ``x_show_script`` for runtime
+introspection of registered SCRIPT blocks.
 """
 
+from pathlib import Path
 from typing import Any
 
 import execsql.state as _state
+from execsql.utils.errors import fatal_error
 from execsql.utils.fileio import EncodedFile, filewriter_open_as_new, filewriter_write
 
 
@@ -173,3 +177,87 @@ def x_debug_write_config(**kwargs: Any) -> None:
 
     for line in lines:
         write(f"{line}\n")
+
+
+# ---------------------------------------------------------------------------
+# Helpers for SCRIPT introspection (shared by metacommands and REPL)
+# ---------------------------------------------------------------------------
+
+
+def _format_script_signature(name: str, param_defs: Any) -> str:
+    """Return ``name(param1, param2, opt=default)`` or ``name()``.
+
+    *param_defs* may be a list of :class:`ParamDef` objects (preferred) or
+    a plain list of strings (backward compat).
+    """
+    if not param_defs:
+        return f"{name}()"
+    parts: list[str] = []
+    for p in param_defs:
+        if hasattr(p, "default") and p.default is not None:
+            parts.append(f"{p.name}={p.default}")
+        elif hasattr(p, "name"):
+            parts.append(p.name)
+        else:
+            parts.append(str(p))
+    return f"{name}({', '.join(parts)})"
+
+
+def _format_script_source(span: Any) -> str:
+    """Return ``file:start-end`` from a SourceSpan."""
+    filename = Path(span.file).name if span and span.file else "<unknown>"
+    if span and span.start_line is not None:
+        if span.end_line is not None and span.end_line != span.start_line:
+            return f"{filename}:{span.start_line}-{span.end_line}"
+        return f"{filename}:{span.start_line}"
+    return filename
+
+
+# ---------------------------------------------------------------------------
+# SHOW SCRIPTS / SHOW SCRIPT metacommand handlers
+# ---------------------------------------------------------------------------
+
+
+def x_show_scripts(**kwargs: Any) -> None:
+    """List all registered SCRIPT definitions with parameters and source location."""
+    scripts = _state.ast_scripts
+    if not scripts:
+        _state.output.write("No scripts registered.\n")
+        return
+    _state.output.write(f"Registered scripts ({len(scripts)}):\n\n")
+    # Compute column width for alignment
+    sigs = {name: _format_script_signature(name, block.param_defs) for name, block in scripts.items()}
+    max_sig = max(len(s) for s in sigs.values())
+    for name, block in scripts.items():
+        sig = sigs[name]
+        src = _format_script_source(block.span)
+        _state.output.write(f"  {sig:<{max_sig}}  {src}\n")
+    _state.output.write("\n")
+
+
+def x_show_script(**kwargs: Any) -> None:
+    """Show detail for a single registered SCRIPT definition."""
+    script_name = kwargs.get("script_id", "").lower()
+    scripts = _state.ast_scripts
+    if script_name not in scripts:
+        _state.output.write(f"No script named '{script_name}' is registered.\n")
+        return
+    block = scripts[script_name]
+    sig = _format_script_signature(block.name, block.param_defs)
+    src = _format_script_source(block.span)
+    _state.output.write(f"Script: {sig}\n")
+    _state.output.write(f"Source: {src}\n")
+    if block.param_defs:
+        _state.output.write("Parameters:\n")
+        max_name = max(len(p.name) for p in block.param_defs)
+        for p in block.param_defs:
+            if p.default is not None:
+                _state.output.write(f"  {p.name:<{max_name}}  (optional, default: {p.default})\n")
+            else:
+                _state.output.write(f"  {p.name:<{max_name}}  (required)\n")
+    else:
+        _state.output.write("Parameters: (none)\n")
+    if block.doc:
+        _state.output.write("\n")
+        for doc_line in block.doc.split("\n"):
+            _state.output.write(f"  {doc_line}\n")

{execsql2-2.16.7 → execsql2-2.16.12}/src/execsql/metacommands/dispatch.py

@@ -99,6 +99,8 @@ from execsql.metacommands.debug import (
     x_debug_write_metacommands,
     x_debug_write_odbc_drivers,
     x_debug_write_subvars,
+    x_show_script,
+    x_show_scripts,
 )
 from execsql.debug.repl import x_breakpoint
 from execsql.metacommands.io import (
@@ -1747,6 +1749,22 @@ def build_dispatch_table() -> MetaCommandList:
         run_when_false=False,
     )
 
+    # ------------------------------------------------------------------
+    # SHOW SCRIPTS / SHOW SCRIPT
+    # ------------------------------------------------------------------
+    mcl.add(
+        r"^\s*SHOW\s+SCRIPTS\s*$",
+        x_show_scripts,
+        description="SHOW SCRIPTS",
+        category="action",
+    )
+    mcl.add(
+        r"^\s*SHOW\s+SCRIPT\s+(?P<script_id>\w+)\s*$",
+        x_show_script,
+        description="SHOW SCRIPT",
+        category="action",
+    )
+
     # ------------------------------------------------------------------
     # IF / ORIF / ANDIF / ELSEIF / ELSE / ENDIF
     # ------------------------------------------------------------------

{execsql2-2.16.7 → execsql2-2.16.12}/src/execsql/script/ast.py

@@ -52,6 +52,7 @@ __all__ = [
     "IfBlock",
     "LoopBlock",
     "BatchBlock",
+    "ParamDef",
     "ScriptBlock",
     "SqlBlock",
     "IncludeDirective",
@@ -290,6 +291,24 @@ class BatchBlock(Node):
         return f"BatchBlock({self.span}, body={len(self.body)})"
 
 
+@dataclass(frozen=True, slots=True)
+class ParamDef:
+    """A single SCRIPT parameter definition with an optional default value.
+
+    Attributes:
+        name: The parameter name (as declared, without ``#`` prefix).
+        default: The default value string, or ``None`` for required parameters.
+    """
+
+    name: str
+    default: str | None = None
+
+    @property
+    def required(self) -> bool:
+        """Return ``True`` if this parameter has no default value."""
+        return self.default is None
+
+
 @dataclass
 class ScriptBlock(Node):
     """A BEGIN SCRIPT name ... END SCRIPT structure.
@@ -299,20 +318,31 @@ class ScriptBlock(Node):
 
     Attributes:
         name: The script block name (lowercased).
-        param_names: Optional list of formal parameter names.
+        param_defs: Optional list of :class:`ParamDef` parameter definitions.
+        doc: Optional docstring extracted from comments immediately following
+            the BEGIN SCRIPT line.
         body: Nodes within the script block.
     """
 
     name: str
-    param_names: list[str] | None = None
+    param_defs: list[ParamDef] | None = None
+    doc: str | None = None
     body: list[Node] = field(default_factory=list)
 
+    @property
+    def param_names(self) -> list[str] | None:
+        """Return parameter names only (backward compatibility)."""
+        if self.param_defs is None:
+            return None
+        return [p.name for p in self.param_defs]
+
     def children(self) -> Iterator[Node]:
         yield from self.body
 
     def __repr__(self) -> str:
-        params = f", params={self.param_names}" if self.param_names else ""
-        return f"ScriptBlock({self.span}, name={self.name!r}{params}, body={len(self.body)})"
+        params = f", params={self.param_names}" if self.param_defs else ""
+        doc_tag = ", doc=True" if self.doc else ""
+        return f"ScriptBlock({self.span}, name={self.name!r}{params}{doc_tag}, body={len(self.body)})"
 
 
 @dataclass
@@ -547,8 +577,15 @@ def _node_label(node: Node) -> str:
     if isinstance(node, BatchBlock):
         return f"{_tag('BATCH')} BEGIN BATCH"
     if isinstance(node, ScriptBlock):
-        params = f" ({', '.join(node.param_names)})" if node.param_names else ""
-        return f"{_tag('SCRIPT')} {node.name}{params}"
+        if node.param_defs:
+            parts = []
+            for p in node.param_defs:
+                parts.append(f"{p.name}={p.default}" if p.default is not None else p.name)
+            params = f" ({', '.join(parts)})"
+        else:
+            params = ""
+        doc_tag = " [doc]" if node.doc else ""
+        return f"{_tag('SCRIPT')} {node.name}{params}{doc_tag}"
     if isinstance(node, SqlBlock):
         return f"{_tag('SQL_BLK')} BEGIN SQL"
     if isinstance(node, IncludeDirective):

{execsql2-2.16.7 → execsql2-2.16.12}/src/execsql/script/executor.py

@@ -648,7 +648,10 @@ def _execute_include(
     WHILE/UNTIL loops are handled natively too.
     """
     if node.is_execute_script:
-        target = node.target.lower()
+        # Substitute variables in the target — the script name may be passed
+        # as a parameter (e.g., EXECUTE SCRIPT !!#script_name!!).
+        effective_locals = _stack_localvars(ctx) or localvars
+        target = substitute_vars(node.target, effective_locals, ctx=ctx).strip().lower()
 
         # Native path: target is in our AST registry
         if target in ctx.ast_scripts:
@@ -713,23 +716,35 @@ def _execute_script_native(
         for param, arg in all_prepared_args:
             paramvals.add_substitution(param, arg)
 
-        # Validate parameter names match
-        if script_block.param_names is not None:
+        # Validate parameter names match — with default parameter support
+        if script_block.param_defs is not None:
             passed_names = [p[0].lstrip("#") for p in all_prepared_args]
-            if not all(p in passed_names for p in script_block.param_names):
+            required = [p.name for p in script_block.param_defs if p.required]
+            missing = [p for p in required if p not in passed_names]
+            if missing:
                 raise ErrInfo(
                     "error",
-                    other_msg=f"Formal and actual parameter name mismatch in call to {script_block.name}.",
+                    other_msg=(f"Missing required parameter(s) ({', '.join(missing)}) in call to {script_block.name}."),
                 )
+            # Inject defaults for optional params not provided
+            for pdef in script_block.param_defs:
+                if pdef.default is not None and pdef.name not in passed_names:
+                    paramvals.add_substitution(f"#{pdef.name}", pdef.default)
     else:
-        if script_block.param_names is not None:
-            raise ErrInfo(
-                "error",
-                other_msg=(
-                    f"Missing expected parameters ({', '.join(script_block.param_names)}) "
-                    f"in call to {script_block.name}."
-                ),
-            )
+        if script_block.param_defs is not None:
+            required = [p.name for p in script_block.param_defs if p.required]
+            if required:
+                raise ErrInfo(
+                    "error",
+                    other_msg=(
+                        f"Missing required parameter(s) ({', '.join(required)}) in call to {script_block.name}."
+                    ),
+                )
+            # No args provided but all params have defaults — inject them all
+            paramvals = ScriptArgSubVarSet()
+            for pdef in script_block.param_defs:
+                if pdef.default is not None:
+                    paramvals.add_substitution(f"#{pdef.name}", pdef.default)
 
     # Push a CommandList frame onto the stack so that:
     #   - get_subvarset() can find ~local and +outer-scope variables