execsql2 2.25.1__py3-none-any.whl → 2.27.0__py3-none-any.whl

execsql/cli/commands/__init__.py

@@ -11,3 +11,4 @@ from execsql.cli.commands import lint  # noqa: F401
 from execsql.cli.commands import config  # noqa: F401
 from execsql.cli.commands import listing  # noqa: F401
 from execsql.cli.commands import init  # noqa: F401
+from execsql.cli.commands import lsp  # noqa: F401

execsql/cli/commands/format.py

@@ -51,6 +51,15 @@ def format_cmd(
         help="Commas at the start of lines instead of the end. Default: [format] leading_comma, else off.",
         show_default=False,
     ),
+    rewrite_sql: bool | None = typer.Option(
+        None,
+        "--rewrite-sql/--no-rewrite-sql",
+        help=(
+            "Also let sqlglot rewrite SQL text (x::int as CAST(x AS INT), BTRIM as TRIM, an alias with AS); "
+            "without it such a statement is kept as written. Default: [format] rewrite_sql, else off."
+        ),
+        show_default=False,
+    ),
     script_encoding: ScriptEncodingOpt = None,
     # The old spelling of --script-encoding, kept working but out of --help.
     encoding: str | None = typer.Option(None, "--encoding", metavar="NAME", hidden=True),
@@ -92,6 +101,7 @@ def format_cmd(
             no_sql=no_sql,
             indent=conf.format_indent if indent is None else indent,
             leading_comma=conf.format_leading_comma if leading_comma is None else leading_comma,
+            rewrite_sql=conf.format_rewrite_sql if rewrite_sql is None else rewrite_sql,
             encoding=script_encoding or encoding or _configured_script_encoding(conf) or "utf-8",
         ),
     )

execsql/cli/commands/listing.py

@@ -9,17 +9,21 @@ from __future__ import annotations
 
 import json
 import sys
+from typing import Annotated
 
 import typer
 
 from execsql.cli.application import ExecsqlCommand, ExecsqlSubGroup, app
 from execsql.cli.help import (
+    _err_console,
     _encoding_names,
-    _metacommand_rows,
+    _metacommand_entries,
+    _metacommand_json,
     _plugins_data,
     _print_encodings,
     _print_keywords_json,
     _print_keywords_text,
+    _print_metacommand,
     _print_metacommands,
     _print_plugins,
 )
@@ -43,10 +47,33 @@ def _json(data: object) -> None:
 
 
 @list_app.command(cls=ExecsqlCommand, name="metacommands")
-def metacommands_cmd(output_format: OutputFormatOpt = OutputFormat.text) -> None:
-    """Every metacommand and its syntax."""
-    if output_format is OutputFormat.json:
-        _json([{"name": name, "syntax": syntax} for name, syntax in _metacommand_rows()])
+def metacommands_cmd(
+    keyword: Annotated[
+        list[str] | None,
+        typer.Argument(metavar="[KEYWORD]", help="Show one metacommand's syntax, e.g. EXPORT or export query."),
+    ] = None,
+    output_format: OutputFormatOpt = OutputFormat.text,
+) -> None:
+    """Every metacommand with a one-line summary, or the syntax of one."""
+    if keyword:
+        from execsql.metacommands.reference import metacommand
+
+        wanted = " ".join(keyword)
+        entry = metacommand(wanted)
+        if entry is None:
+            import difflib
+
+            names = [m.keyword for m in _metacommand_entries()]
+            close = difflib.get_close_matches(wanted.upper(), names, n=3)
+            hint = f" Did you mean {', '.join(close)}?" if close else ""
+            _err_console.print(f"[bold red]Error:[/bold red] No metacommand {wanted!r}.{hint}", highlight=False)
+            raise typer.Exit(code=2)
+        if output_format is OutputFormat.json:
+            _json(_metacommand_json(entry))
+        else:
+            _print_metacommand(entry)
+    elif output_format is OutputFormat.json:
+        _json([_metacommand_json(m) for m in _metacommand_entries()])
     else:
         _print_metacommands()
 

execsql/cli/commands/lsp.py

@@ -0,0 +1,40 @@
+"""The ``lsp`` command: the language server editors start for ``.sql`` files."""
+
+from __future__ import annotations
+
+import typer
+
+from execsql.cli.application import ExecsqlCommand, app
+from execsql.cli.help import _err_console
+
+__all__ = ["lsp_cmd"]
+
+
+@app.command(
+    cls=ExecsqlCommand,
+    name="lsp",
+    help=(
+        "Run the execsql language server on stdin/stdout, for an editor to start. "
+        "Shows execsql lint findings as you type, completes metacommands, "
+        "conditional tests and variables, explains them on hover, and finds where variables, "
+        "SCRIPTs and included files are defined, offers quick fixes, and formats documents. Needs the lsp extra "
+        "(installed with any extras you already have, e.g. execsql2[postgres,lsp])."
+    ),
+)
+def lsp_cmd(
+    # Editors' language clients pass --stdio (VS Code always does); stdio is the only transport.
+    stdio: bool = typer.Option(False, "--stdio", hidden=True),
+) -> None:
+    """The ``lsp`` command; its user-facing help is the decorator's ``help``."""
+    try:
+        from execsql.lsp.server import create_server
+    except ImportError as exc:
+        _err_console.print(
+            "[bold red]Error:[/bold red] execsql lsp needs the lsp extra. Install it with the "
+            'extras you already have, e.g. uv tool install "execsql2\\[postgres,lsp]" or '
+            'pipx install --force "execsql2\\[postgres,lsp]". '
+            "See https://execsql2.readthedocs.io/en/latest/getting-started/installation/#adding-an-extra-later",
+            highlight=False,
+        )
+        raise typer.Exit(code=1) from exc
+    create_server().start_io()

execsql/cli/dispatch.py

@@ -29,7 +29,7 @@ from __future__ import annotations
 __all__ = ["COMMANDS", "GLOBAL_FLAGS", "dispatch", "normalize"]
 
 #: Tokens that name a command.
-COMMANDS = ("run", "format", "lint", "config", "list", "init")
+COMMANDS = ("run", "format", "lint", "config", "list", "init", "lsp")
 
 #: Options declared on the app rather than on a command, which must reach
 #: the parser without ``run`` in front of them. ``-m``, ``--encodings`` and

execsql/cli/help.py

@@ -19,7 +19,9 @@ __all__ = [
     "_init_config",
     "_init_config_text",
     "_keywords_data",
-    "_metacommand_rows",
+    "_metacommand_entries",
+    "_metacommand_json",
+    "_print_metacommand",
     "_plugins_data",
     "_print_encodings",
     "_print_keywords_json",
@@ -31,66 +33,6 @@ __all__ = [
 _console = Console()
 _err_console = Console(stderr=True)
 
-# ---------------------------------------------------------------------------
-# Metacommand syntax hints — paired with keywords from the dispatch table.
-# Keys must match the ``description`` values used in mcl.add() calls.
-# Entries here are validated by tests/test_registry.py.
-# ---------------------------------------------------------------------------
-
-_SYNTAX: dict[str, tuple[str, str]] = {
-    # (display_name, syntax_hint)
-    "ASK": ("ASK", '"<question>" SUB <match_string>'),
-    "AUTOCOMMIT": ("AUTOCOMMIT", "ON|OFF"),
-    "BEGIN BATCH": ("BEGIN BATCH / END BATCH / ROLLBACK BATCH", ""),
-    "BEGIN SCRIPT": ("BEGIN SCRIPT / END SCRIPT", ""),
-    "BEGIN SQL": ("BEGIN SQL / END SQL", ""),
-    "CANCEL_HALT": ("CANCEL_HALT", "ON|OFF"),
-    "CD": ("CD", "<directory>"),
-    "CONNECT": ("CONNECT", "<alias> [AS <alias_name>]"),
-    "COPY": ("COPY", "<source_file> TO <dest_file>"),
-    "DEBUG": ("DEBUG", "ON|OFF"),
-    "SUB": ("DEFINE SUB", "<variable> [AS] <value>"),
-    "EXPORT QUERY": ("EXPORT QUERY", "<queryname> [AS <alias>] ..."),
-    "EXPORT": ("EXPORT", "<queryname> TO <format> <filename> ..."),
-    "HALT": ("HALT [ON]", "ERROR|CANCEL"),
-    "IF": ("IF <condition>", "/ ELSE / ENDIF"),
-    "IMPORT_FILE": ("IMPORT FILE", "<filename> [OPTIONS ...]"),
-    "IMPORT": ("IMPORT TABLE", "<tablename> FROM FILE <filename> [OPTIONS ...]"),
-    "LOOP": ("LOOP <n> TIMES | WHILE | UNTIL", "/ END LOOP"),
-    "CONFIG": ("CONFIG", "<option> <value>"),
-    "ON CANCEL_HALT": ("ON CANCEL_HALT", "..."),
-    "ON ERROR_HALT": ("ON ERROR_HALT", "..."),
-    "PAUSE": ("PAUSE", "[<text>]"),
-    "PROMPT ACTION": ("PROMPT ACTION", "..."),
-    "PROMPT ENTRY_FORM": ("PROMPT ENTRY_FORM", "..."),
-    "PROMPT OPENFILE": ("PROMPT OPENFILE", "..."),
-    "PROMPT SAVEFILE": ("PROMPT SAVEFILE", "..."),
-    "PROMPT DIRECTORY": ("PROMPT DIRECTORY", "..."),
-    "PROMPT MAP": ("PROMPT MAP", "..."),
-    "ROLLBACK BATCH": ("ROLLBACK", ""),
-    "SERVE": ("SERVE", "<queryname> ..."),
-    "SYSTEM_CMD": ("SYSTEM_CMD", "(<operating system command line>)"),
-    "TIMER": ("TIMER", "ON|OFF"),
-    "USE": ("USE", "<alias_name>"),
-    "WAIT_UNTIL": ("WAIT_UNTIL", "<Boolean_expression> <HALT|CONTINUE> AFTER <n> SECONDS"),
-    "WRITE": ("WRITE", '"<text>" [[TEE] TO <output>]'),
-    "WRITE CREATE_TABLE": ("WRITE CREATE_TABLE FROM", "<filename> [TO <output>]"),
-    "WRITE SCRIPT": ("WRITE SCRIPT", "<script_name> [[APPEND] TO <output_file>]"),
-    "ZIP": ("ZIP", "<filename> [APPEND] TO ZIPFILE <zipfilename>"),
-    "SUB_TEMPFILE": ("SUB_TEMPFILE", "<variable>"),
-}
-
-# Keys from _SYNTAX that should be skipped when auto-generating from dispatch
-# table (they're variants covered by another entry).
-_SKIP_FROM_DISPATCH = {
-    "END BATCH",
-    "END SCRIPT",
-    "END SQL",
-    "ROLLBACK BATCH",
-    "BEGIN SCRIPT",
-    "BEGIN SQL",
-}
-
 
 def _init_config_text() -> str:
     """The default execsql.conf template, every option commented out and documented."""
@@ -106,56 +48,62 @@ def _init_config() -> None:
     sys.stdout.write(_init_config_text())
 
 
-def _metacommand_rows() -> list[tuple[str, str]]:
-    """``(name, syntax)`` for every metacommand, in the order they are listed.
+_CATEGORY_ORDER = ("control", "block", "action", "config", "prompt")
 
-    Keyword list is derived from the dispatch table; syntax hints come from
-    the ``_SYNTAX`` dict above.  Keywords not in ``_SYNTAX`` get an empty
-    syntax hint.
-    """
-    from execsql.metacommands import DISPATCH_TABLE
-
-    # Collect unique keyword names from the dispatch table.
-    seen: set[str] = set()
-    keywords: list[str] = []
-    for mc in DISPATCH_TABLE:
-        if mc.description and mc.description not in seen and mc.description not in _SKIP_FROM_DISPATCH:
-            seen.add(mc.description)
-            keywords.append(mc.description)
-    # Add parser-level keywords not in the dispatch table.
-    for extra in ("BEGIN BATCH", "BEGIN SCRIPT", "BEGIN SQL"):
-        if extra not in seen:
-            seen.add(extra)
-            keywords.append(extra)
-
-    rows: list[tuple[str, str]] = []
-    for kw in sorted(keywords):
-        if kw in _SYNTAX:
-            rows.append(_SYNTAX[kw])
-        elif kw.startswith("CONFIG ") or kw.startswith("CONSOLE_") or "_" in kw:
-            continue  # skip config options / internal entries
-        else:
-            rows.append((kw, ""))
-    return rows
+
+def _metacommand_entries() -> list[Any]:
+    """Every metacommand's readable entry, by category, then keyword."""
+    from execsql.metacommands.reference import metacommands
+
+    order = {c: i for i, c in enumerate(_CATEGORY_ORDER)}
+    return sorted(metacommands(), key=lambda m: (order.get(m.category, len(order)), m.keyword))
+
+
+def _metacommand_json(entry: Any) -> dict[str, Any]:
+    return {
+        "name": entry.keyword,
+        "category": entry.category,
+        "syntax": entry.forms[0],
+        "forms": list(entry.forms),
+        "summary": entry.summary,
+        "url": entry.url,
+    }
 
 
 def _print_metacommands() -> None:
-    """Print the metacommands table using Rich."""
+    """Print every metacommand with its category and one-line summary."""
     table = Table(
         title="execsql Metacommands",
-        caption="Embed in SQL comment lines following the [bold]!x![/bold] token.",
+        caption=(
+            "Write them in a SQL comment after [bold]-- !x![/bold].  "
+            "[bold]execsql list metacommands <KEYWORD>[/bold] shows the syntax of one."
+        ),
         show_header=True,
         header_style="bold cyan",
         border_style="dim",
         expand=False,
     )
     table.add_column("Metacommand", style="bold green", no_wrap=True)
-    table.add_column("Syntax", style="white")
-    for name, syntax in _metacommand_rows():
-        table.add_row(name, syntax)
+    table.add_column("Category", style="dim", no_wrap=True)
+    table.add_column("Summary", style="white")
+    for entry in _metacommand_entries():
+        table.add_row(entry.keyword, entry.category, entry.summary)
     _console.print(table)
 
 
+def _print_metacommand(entry: Any) -> None:
+    """Print one metacommand's syntax lines, summary and docs link."""
+    from rich.markup import escape
+
+    _console.print(f"[bold green]{escape(entry.keyword)}[/bold green]  [dim]{entry.category}[/dim]")
+    _console.print(escape(entry.summary))
+    _console.print()
+    for form in entry.forms:
+        _console.print(f"  -- !x! {escape(form)}", highlight=False)
+    _console.print()
+    _console.print(f"[dim]{entry.url}[/dim]", highlight=False)
+
+
 def _encoding_names() -> list[str]:
     """Every encoding name Python accepts, sorted."""
     return sorted(codec_dict.keys())

execsql/cli/lint.py

@@ -82,6 +82,7 @@ __all__ = [
     "filter_issues",
     "lint",
     "lint_source",
+    "variables_defined_by",
     "parse_error",
     "print_concise",
     "print_statistics",
@@ -430,6 +431,18 @@ def _extract_var_definition(
             _read_ini_vars(ini_file, ini_section, script_dir, defined)
 
 
+def variables_defined_by(command: str, script_dir: Path | None = None) -> set[str]:
+    """The variable names (upper case, without ``~``/``+``) a metacommand defines.
+
+    *command* is the text after ``-- !x!``.  Covers the SUB family, the
+    prompts that store an answer, SUB_QUERYSTRING and SUB_INI (whose INI file
+    is read, relative to *script_dir*).
+    """
+    defined: set[str] = set()
+    _extract_var_definition(command, script_dir, defined)
+    return defined
+
+
 # Larger than any real SUB_INI file; lint reads no more than this.
 _MAX_INI_BYTES = 1024 * 1024
 

execsql/config.py

@@ -379,6 +379,7 @@ class ConfigData:
         self._get_int(cp, self._FORMAT_SECTION, "indent", "format_indent")
         self._get_bool(cp, self._FORMAT_SECTION, "leading_comma", "format_leading_comma")
         self._get_bool(cp, self._FORMAT_SECTION, "sql", "format_sql")
+        self._get_bool(cp, self._FORMAT_SECTION, "rewrite_sql", "format_rewrite_sql")
         self._get_str(cp, self._LINT_SECTION, "select", "lint_select")
         self._get_str(cp, self._LINT_SECTION, "ignore", "lint_ignore")
         self._get_bool(cp, self._LINT_SECTION, "strict", "lint_strict")
@@ -555,6 +556,7 @@ class ConfigData:
         self.format_indent = 4
         self.format_leading_comma = False
         self.format_sql = True
+        self.format_rewrite_sql = False
         self.lint_select: str | None = None
         self.lint_ignore: str | None = None
         self.lint_strict = False

execsql/data/execsql.conf.template

@@ -369,6 +369,9 @@
 #leading_comma=No
 # Reformat SQL with sqlglot (needs the [formatter] extra). No = metacommands only.
 #sql=Yes
+# Also let sqlglot rewrite SQL text: x::int as CAST(x AS INT), BTRIM as TRIM,
+# an alias with AS. No = a statement it would rewrite is kept as written.
+#rewrite_sql=No
 
 
 [lint]

execsql/format.py

@@ -16,6 +16,7 @@ import io
 import re
 from collections.abc import Iterator
 from pathlib import Path
+from types import ModuleType
 
 __all__ = ["collect_paths", "format_file", "open_dollar_quote", "parse_keyword", "run_formatter"]
 
@@ -509,10 +510,47 @@ def _is_comment_line(line: str, in_block: bool) -> tuple[bool, bool]:
     return False, False
 
 
+def _statement_sources(sqlglot: ModuleType, sql: str) -> list[str]:
+    """The text of each statement in *sql*, split at the semicolons sqlglot's tokenizer sees.
+
+    Comments before a statement belong to it; a semicolon inside a string or
+    a quoted name is not a split.  A part holding no tokens (``;;``) is not a
+    statement, matching the ``None`` sqlglot's parser returns for it.
+    """
+    sources: list[str] = []
+    start = 0
+    has_tokens = False
+    for token in sqlglot.tokenize(sql, read="postgres"):
+        if token.token_type.name == "SEMICOLON":
+            if has_tokens:
+                sources.append(sql[start : token.start])
+            start, has_tokens = token.end + 1, False
+        else:
+            has_tokens = True
+    if has_tokens:
+        sources.append(sql[start:])
+    return sources
+
+
+def _layout_tokens(sqlglot: ModuleType, sql: str) -> list[str]:
+    """*sql*'s tokens with everything the formatter may change taken out.
+
+    Whitespace and comments are not tokens.  Keywords and unquoted names are
+    compared without case; strings and quoted names exactly.
+    """
+    return [
+        token.text
+        if token.token_type.name.endswith("STRING") or token.token_type.name == "IDENTIFIER"
+        else token.text.upper()
+        for token in sqlglot.tokenize(sql, read="postgres")
+    ]
+
+
 def _sqlglot_format(
     sql_lines: list[str],
     sql_indent: int = 4,
     leading_comma: bool = False,  # noqa: ARG001 — leading-comma layout is applied as a textual post-pass on the assembled output; sqlglot's own `leading_comma=True` is non-idempotent under inline comments.
+    rewrite_sql: bool = False,
 ) -> list[str]:
     """Format a list of SQL-only lines (no comment-only lines) via sqlglot.
 
@@ -521,6 +559,12 @@ def _sqlglot_format(
     ``format_file``. sqlglot's own ``leading_comma=True`` reshuffles inline
     comments and is therefore non-idempotent on SQL with mid-statement
     comments, which is the dominant real-world case.
+
+    sqlglot also rewrites SQL into its preferred form (``x::int`` ->
+    ``CAST(x AS INT)``, ``BTRIM`` -> ``TRIM``, an alias gains ``AS``), and
+    which rewrites it makes changes between its releases (#72).  Unless
+    *rewrite_sql*, a statement whose tokens would change beyond keyword case
+    is kept as written.
     """
     sqlglot = _require_sqlglot()
     import sqlglot.errors as sqlglot_errors
@@ -551,24 +595,28 @@ def _sqlglot_format(
             # understood the whole statement, so ask it: input that does not
             # parse is left exactly as written.
             ast = sqlglot.parse(protected, read="postgres", error_level=sqlglot_errors.ErrorLevel.RAISE)
+            nodes = [node for node in ast if node is not None]
+            sources = None if rewrite_sql else _statement_sources(sqlglot, protected)
+            if sources is not None and len(sources) != len(nodes):
+                return sql_lines
             statements: list[str] = []
-            for node in ast:
-                if node is None:
-                    continue
+            for i, node in enumerate(nodes):
                 # For Command nodes (psql backslash commands, ERROR:, etc.)
                 # use unpretty output to avoid mangling.
                 if type(node).__name__ == "Command":
-                    statements.append(node.sql(dialect="postgres"))
+                    generated = node.sql(dialect="postgres")
                 else:
-                    statements.append(
-                        node.sql(
-                            dialect="postgres",
-                            pretty=True,
-                            pad=sql_indent,
-                            indent=sql_indent,
-                            max_text_width=120,
-                        ),
+                    generated = node.sql(
+                        dialect="postgres",
+                        pretty=True,
+                        pad=sql_indent,
+                        indent=sql_indent,
+                        max_text_width=120,
                     )
+                generated = re.sub(r"\bINTO TEMPORARY\b(?!\s+TABLE)", "INTO TEMPORARY TABLE", generated)
+                if sources is not None and _layout_tokens(sqlglot, generated) != _layout_tokens(sqlglot, sources[i]):
+                    generated = sources[i].lstrip("\n").rstrip()  # layout only: keep it as written
+                statements.append(generated)
         stmts = [s for s in statements if s]
         if not stmts:
             return sql_lines
@@ -613,7 +661,6 @@ def _sqlglot_format(
         if set(_sql_literal_texts(protected)) - set(_sql_literal_texts(joined)):
             return sql_lines
 
-        joined = re.sub(r"\bINTO TEMPORARY\b(?!\s+TABLE)", "INTO TEMPORARY TABLE", joined)
         restored = _restore_estrings(joined, estrings)
         if restored is None:
             return sql_lines
@@ -701,6 +748,7 @@ def _format_preserving_comments(
     lines: list[str],
     sql_indent: int = 4,
     leading_comma: bool = False,
+    rewrite_sql: bool = False,
 ) -> list[str]:
     """Format SQL with interleaved comments via marker-based round-tripping.
 
@@ -744,8 +792,12 @@ def _format_preserving_comments(
             pending_markers.append(mid)
         else:
             # SQL line — prepend any pending markers as inline comments
+            # After the line's indentation, not before it: a statement that
+            # comes back as written (unparsable, or kept by layout-only) has
+            # its indentation read from this line once the marker is removed.
             prefix = " ".join(f"/* {m} */" for m in pending_markers)
-            processed.append(f"{prefix} {line}" if prefix else line)
+            body = line.lstrip()
+            processed.append(f"{line[: len(line) - len(body)]}{prefix} {body}" if prefix else line)
             for m in pending_markers:
                 anchor_sql[m] = stripped
                 anchor_line[m] = len(processed) - 1
@@ -760,7 +812,7 @@ def _format_preserving_comments(
     anchor_depth: dict[str, int] = {m: in_depths[i] for m, i in anchor_line.items()}
 
     # ---- Step 2: format through sqlglot ---------------------------------
-    formatted = _sqlglot_format(processed, sql_indent=sql_indent, leading_comma=leading_comma)
+    formatted = _sqlglot_format(processed, sql_indent=sql_indent, leading_comma=leading_comma, rewrite_sql=rewrite_sql)
 
     # ---- Step 3: restore surviving markers to comment lines -------------
     found_markers: set[str] = set()
@@ -908,6 +960,7 @@ def format_sql_block(
     indent: int,
     use_sql: bool,
     leading_comma: bool = False,
+    rewrite_sql: bool = False,
 ) -> list[str]:
     """Re-indent a SQL block to the current depth, optionally formatting via sqlglot."""
     if not lines:
@@ -940,7 +993,12 @@ def format_sql_block(
     # which preserves both comments AND sqlglot formatting.  When all
     # comments are between statements, the simpler segmentation works.
     if _has_mid_statement_comments(rebased):
-        formatted_lines = _format_preserving_comments(rebased, sql_indent=indent, leading_comma=leading_comma)
+        formatted_lines = _format_preserving_comments(
+            rebased,
+            sql_indent=indent,
+            leading_comma=leading_comma,
+            rewrite_sql=rewrite_sql,
+        )
         return [target_prefix + line if line.strip() else "" for line in formatted_lines]
 
     result: list[str] = []
@@ -954,7 +1012,7 @@ def format_sql_block(
         if seg_is_comment:
             result.extend(seg)
         else:
-            result.extend(_sqlglot_format(seg, sql_indent=indent, leading_comma=leading_comma))
+            result.extend(_sqlglot_format(seg, sql_indent=indent, leading_comma=leading_comma, rewrite_sql=rewrite_sql))
         seg.clear()
 
     for line in rebased:
@@ -1076,8 +1134,19 @@ def _apply_leading_comma(text: str) -> str:
     return "\n".join(lines)
 
 
-def format_file(source: str, indent: int = 4, use_sql: bool = True, leading_comma: bool = False) -> str:
-    """Format the source text of an execsql script and return the result."""
+def format_file(
+    source: str,
+    indent: int = 4,
+    use_sql: bool = True,
+    leading_comma: bool = False,
+    rewrite_sql: bool = False,
+) -> str:
+    """Format the source text of an execsql script and return the result.
+
+    SQL is laid out by sqlglot.  A statement sqlglot would also rewrite
+    (``x::int`` as ``CAST(x AS INT)``, ``BTRIM`` as ``TRIM``, an alias with
+    ``AS``) is kept as written unless *rewrite_sql*.
+    """
     # Normalize any leading-comma SQL in the source to trailing commas so
     # that sqlglot always sees the same comma shape regardless of how
     # the user saved the file. The post-pass at the bottom of this
@@ -1124,7 +1193,16 @@ def format_file(source: str, indent: int = 4, use_sql: bool = True, leading_comm
             # `sql_acc_contains_dollar_quote` catches the case where the region
             # already closed (`... $$;`) so `in_dollar_quote` is False at flush.
             safe_for_sqlglot = use_sql and not in_dollar_quote and not sql_acc_contains_dollar_quote
-            output.extend(format_sql_block(sql_acc, depth, indent, safe_for_sqlglot, leading_comma=leading_comma))
+            output.extend(
+                format_sql_block(
+                    sql_acc,
+                    depth,
+                    indent,
+                    safe_for_sqlglot,
+                    leading_comma=leading_comma,
+                    rewrite_sql=rewrite_sql,
+                ),
+            )
             sql_acc.clear()
         in_sql_statement = False
         sql_acc_contains_dollar_quote = False
@@ -1243,6 +1321,7 @@ def run_formatter(
     no_sql: bool = False,
     indent: int = 4,
     leading_comma: bool = False,
+    rewrite_sql: bool = False,
     encoding: str = "utf-8",
     diff: bool = False,
 ) -> int:
@@ -1290,7 +1369,13 @@ def run_formatter(
             any_errors = True
             continue
 
-        formatted = format_file(source, indent=indent, use_sql=use_sql, leading_comma=leading_comma)
+        formatted = format_file(
+            source,
+            indent=indent,
+            use_sql=use_sql,
+            leading_comma=leading_comma,
+            rewrite_sql=rewrite_sql,
+        )
 
         if diff:
             if formatted != source:

execsql/lsp/__init__.py

@@ -0,0 +1,6 @@
+"""Language server for execsql scripts: ``execsql lsp``.
+
+Editors start it over stdio. The features are plain functions over a
+document's text, so they are tested without a client; :mod:`.server` wires
+them to the protocol with pygls (the ``lsp`` extra).
+"""