Quantar 0.1.0__py3-none-any.whl

lang_systems/__init__.py

@@ -0,0 +1,38 @@
+"""Quantar language systems - parsers, ASTs, and language tools.
+
+``lang_systems.parse`` returns pegen's raw parse tree.  ``lang_systems.parse_ast``
+returns a Python AST with custom :class:`QuantumOp` nodes.  Both are imported
+lazily so that importing this package does not require the generated parser
+(which is produced at build time) to already exist.
+"""
+
+import importlib
+
+__version__ = "0.1.0"
+
+_EXPORTS = {
+    "parse": ("lang_systems.quantar", "parse"),
+    "parse_ast": ("lang_systems.ast_builder", "parse_ast"),
+    "build_ast": ("lang_systems.ast_builder", "build_ast"),
+    "lower_ast": ("lang_systems.ast_builder", "lower_ast"),
+    "compile_ast": ("lang_systems.ast_builder", "compile_ast"),
+    "QuantumOp": ("lang_systems.ast_builder", "QuantumOp"),
+    "LowerQuantumOps": ("lang_systems.ast_builder", "LowerQuantumOps"),
+    "load_operators": ("lang_systems.operators", "load_operators"),
+    "list_known_operators": ("lang_systems.operators", "list_known_operators"),
+    "QuantarNodeVisitor": ("lang_systems.visitors", "QuantarNodeVisitor"),
+    "OperatorCollector": ("lang_systems.visitors", "OperatorCollector"),
+}
+
+
+def __getattr__(name):
+    target = _EXPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    module_name, attribute = target
+    value = getattr(importlib.import_module(module_name), attribute)
+    globals()[name] = value
+    return value
+
+
+__all__ = list(_EXPORTS)

lang_systems/ast_builder.py

@@ -0,0 +1,272 @@
+"""Build a Python AST for Quantar source.
+
+Quantar adds a handful of infix operators to Python's syntax.  Reimplementing
+CPython's grammar would be wasteful, so this module takes the opposite route:
+
+1. recursively find custom infix expressions in the pegen parse tree;
+2. replace each one with a unique sentinel call;
+3. hand the resulting text to :func:`ast.parse`;
+4. replace the sentinel calls with :class:`QuantumOp` nodes.
+
+The result is ordinary Python AST plus custom :class:`QuantumOp` nodes, which
+can then be inspected with :mod:`lang_systems.visitors` or lowered back to calls.
+"""
+
+from __future__ import annotations
+
+import ast
+import token
+import tokenize
+from dataclasses import dataclass
+from types import CodeType
+
+from lang_systems.operators import get_known_operator_kind
+from lang_systems.quantar import parse
+from lang_systems.quantar_tokens import tokenize_source
+
+_SENTINEL_PREFIX = "__quantar_operator_"
+_SENTINEL_SUFFIX = "__"
+
+
+class QuantumOp(ast.expr):
+    """A Quantar infix operation, stored as a first-class AST node."""
+
+    _fields = ("operator", "operands", "kind")
+
+    def __init__(
+        self,
+        operator: str,
+        operands: list[ast.expr],
+        kind: str = "binary",
+        **kwargs,
+    ):
+        super().__init__(**kwargs)
+        self.operator = operator
+        self.operands = operands
+        self.kind = kind
+
+
+@dataclass
+class _Rewrite:
+    name: str
+    operator: str
+    kind: str
+    start: tuple[int, int]
+    end: tuple[int, int]
+
+
+class _Source:
+    """Map token positions (line, column) to source offsets and slices."""
+
+    def __init__(self, text: str):
+        self.text = text
+        self.lines = text.splitlines(keepends=True)
+        self.starts: list[int] = []
+        offset = 0
+        for line in self.lines:
+            self.starts.append(offset)
+            offset += len(line)
+
+    def offset(self, position: tuple[int, int]) -> int:
+        row, column = position
+        if row < 1 or row > len(self.starts):
+            return len(self.text)
+        return self.starts[row - 1] + column
+
+    def slice(self, start: tuple[int, int], end: tuple[int, int]) -> str:
+        return self.text[self.offset(start) : self.offset(end)]
+
+    def line(self, row: int) -> str:
+        if 1 <= row <= len(self.lines):
+            return self.lines[row - 1]
+        return ""
+
+    def byte_column(self, position: tuple[int, int]) -> int:
+        _, column = position
+        return len(self.line(position[0])[:column].encode("utf-8"))
+
+
+def _first_token(node) -> tokenize.TokenInfo | None:
+    if isinstance(node, tokenize.TokenInfo):
+        return node
+    if isinstance(node, list):
+        for item in node:
+            found = _first_token(item)
+            if found is not None:
+                return found
+    return None
+
+
+def _last_token(node) -> tokenize.TokenInfo | None:
+    if isinstance(node, tokenize.TokenInfo):
+        return node
+    if isinstance(node, list):
+        for item in reversed(node):
+            found = _last_token(item)
+            if found is not None:
+                return found
+    return None
+
+
+def _custom_operator(node) -> tokenize.TokenInfo | None:
+    """Return the operator token if `node` is a custom binary expression."""
+    if not isinstance(node, list) or len(node) != 3:
+        return None
+    left, middle, right = node
+    if not isinstance(middle, tokenize.TokenInfo):
+        return None
+    if middle.type not in (token.OP, token.NAME):
+        return None
+    if get_known_operator_kind(middle.string) is None:
+        return None
+    if left is None or right is None:
+        return None
+    return middle
+
+
+def _direct_custom_nodes(node) -> list:
+    """Return the outermost custom expressions inside a standard node."""
+    found = []
+
+    def visit(value):
+        if _custom_operator(value) is not None:
+            found.append(value)
+            return
+        if isinstance(value, list):
+            for item in value:
+                visit(item)
+
+    visit(node)
+    return found
+
+
+def _node_text(node, source: _Source) -> str:
+    if isinstance(node, tokenize.TokenInfo):
+        return node.string
+    if not isinstance(node, list):
+        return ""
+    first = _first_token(node)
+    last = _last_token(node)
+    if first is None or last is None:
+        return ""
+    return source.slice(first.start, last.end)
+
+
+def _render(node, source: _Source, rewrites: list[_Rewrite]) -> str:
+    operator = _custom_operator(node)
+    if operator is not None:
+        left, _, right = node
+        first = _first_token(node)
+        last = _last_token(node)
+        if first is None or last is None:
+            return _node_text(node, source)
+
+        name = f"{_SENTINEL_PREFIX}{len(rewrites)}{_SENTINEL_SUFFIX}"
+        kind = get_known_operator_kind(operator.string) or "binary"
+        rewrites.append(_Rewrite(name, operator.string, kind, first.start, last.end))
+
+        left_text = _render(left, source, rewrites)
+        right_text = _render(right, source, rewrites)
+        return f"{name}({operator.string!r}, ({left_text}), ({right_text}))"
+
+    if isinstance(node, tokenize.TokenInfo):
+        return node.string
+
+    text = _node_text(node, source)
+    if not text:
+        return text
+
+    first = _first_token(node)
+    if first is None:
+        return text
+    base = source.offset(first.start)
+    replacements = []
+    for child in _direct_custom_nodes(node):
+        child_first = _first_token(child)
+        child_last = _last_token(child)
+        if child_first is None or child_last is None:
+            continue
+        start = source.offset(child_first.start) - base
+        end = source.offset(child_last.end) - base
+        replacements.append((start, end, _render(child, source, rewrites)))
+
+    for start, end, replacement in sorted(replacements, reverse=True):
+        text = text[:start] + replacement + text[end:]
+    return text
+
+
+class _ReplaceSentinels(ast.NodeTransformer):
+    def __init__(self, rewrites: list[_Rewrite], source: _Source):
+        self.rewrites = {rewrite.name: rewrite for rewrite in rewrites}
+        self.source = source
+
+    def visit_Call(self, node: ast.Call):
+        if not (isinstance(node.func, ast.Name) and node.func.id in self.rewrites):
+            return self.generic_visit(node)
+
+        node = self.generic_visit(node) #type: ignore
+        rewrite = self.rewrites[node.func.id] #type: ignore
+        if len(node.args) != 3:
+            return node
+
+        result = QuantumOp(rewrite.operator, [node.args[1], node.args[2]], rewrite.kind)
+        result.lineno = rewrite.start[0]
+        result.col_offset = self.source.byte_column(rewrite.start)
+        result.end_lineno = rewrite.end[0]
+        result.end_col_offset = self.source.byte_column(rewrite.end)
+        return result
+
+
+class LowerQuantumOps(ast.NodeTransformer):
+    """Lower :class:`QuantumOp` nodes to ``__quantar_apply__(name, *operands)``."""
+
+    def visit_QuantumOp(self, node: QuantumOp):
+        node = self.generic_visit(node) #type: ignore
+        call = ast.Call(
+            func=ast.Name(id="__quantar_apply__", ctx=ast.Load()),
+            args=[ast.Constant(node.operator), *node.operands],
+            keywords=[],
+        )
+        return ast.copy_location(call, node)
+
+
+def parse_ast(source: str, filename: str = "<quantar>") -> ast.Module:
+    """Parse Quantar source into a Python AST containing :class:`QuantumOp` nodes."""
+    source_map = _Source(source)
+    rewrites: list[_Rewrite] = []
+    rewritten = _render(parse(source), source_map, rewrites)
+    tree = ast.parse(rewritten, filename=filename)
+    tree = _ReplaceSentinels(rewrites, source_map).visit(tree)
+    ast.fix_missing_locations(tree)
+    return tree
+
+
+def lower_ast(tree: ast.AST) -> ast.AST:
+    """Return `tree` with all :class:`QuantumOp` nodes lowered to calls."""
+    lowered = LowerQuantumOps().visit(tree)
+    ast.fix_missing_locations(lowered)
+    return lowered
+
+
+def compile_ast(tree: ast.AST, filename: str = "<quantar>", mode: str = "exec") -> CodeType:
+    """Compile an AST produced by :func:`parse_ast`."""
+    return compile(lower_ast(tree), filename, mode) #type: ignore
+
+
+def tokenize_ast(source: str):
+    """Return the token stream used while building an AST (useful for tooling)."""
+    return tokenize_source(source)
+
+
+build_ast = parse_ast
+
+
+__all__ = [
+    "QuantumOp",
+    "LowerQuantumOps",
+    "parse_ast",
+    "build_ast",
+    "lower_ast",
+    "compile_ast",
+    "tokenize_ast",
+]

lang_systems/lsp/__init__.py

@@ -0,0 +1 @@
+"""Language server support for Quantar."""

lang_systems/lsp/__main__.py

@@ -0,0 +1,3 @@
+from lang_systems.lsp.server import main
+
+main()

lang_systems/lsp/server.py

@@ -0,0 +1,247 @@
+"""Quantar language server.
+
+The server deliberately reuses the real tokenizer and parser so editor
+highlighting and diagnostics cannot drift from the language implementation.
+"""
+
+from __future__ import annotations
+
+import keyword
+import logging
+import os
+import sys
+import token
+import tokenize
+
+from lsprotocol import types
+from pygls.lsp.server import LanguageServer
+
+from lang_systems.ast_builder import parse_ast
+from lang_systems.operators import list_known_operators, load_operators
+from lang_systems.quantar_tokens import tokenize_source
+
+TOKEN_TYPES = ("quantarOperator",)
+TOKEN_MODIFIERS = (
+    "nullary",
+    "unary",
+    "binary",
+    "ternary",
+    "callable",
+    "matrix",
+)
+MODIFIER_BITS = {
+    name: 1 << index for index, name in enumerate(TOKEN_MODIFIERS)
+}
+LEGEND = types.SemanticTokensLegend(
+    token_types=list(TOKEN_TYPES),
+    token_modifiers=list(TOKEN_MODIFIERS),
+)
+
+logger = logging.getLogger(__name__)
+
+server = LanguageServer("quantar-lsp", "0.1.0")
+
+
+def _load_default_operators() -> None:
+    """Register the quantum gate operators shipped with Quantar."""
+    try:
+        import quantum.gate_matrix  # noqa: F401
+    except ImportError:
+        logger.debug("Quantum gate operators are not available")
+
+
+def _load_configured_operators() -> None:
+    """Import operator modules listed in QUANTAR_OPERATOR_MODULES."""
+    raw_modules = os.environ.get("QUANTAR_OPERATOR_MODULES", "")
+    modules = [module.strip() for module in raw_modules.split(",") if module.strip()]
+    if not modules:
+        return
+
+    try:
+        load_operators(*modules)
+    except Exception:
+        logger.exception("Failed to load Quantar operator modules: %s", modules)
+
+
+def _position(document, line: int, character: int) -> types.Position:
+    """Convert a Python code-point position into a client position."""
+    return document.position_to_client_units(
+        types.Position(line=max(line, 0), character=max(character, 0))
+    )
+
+
+def _full_range(document) -> types.Range:
+    lines = document.lines
+    if not lines:
+        return types.Range(
+            start=types.Position(line=0, character=0),
+            end=types.Position(line=0, character=0),
+        )
+    last = len(lines) - 1
+    return types.Range(
+        start=types.Position(line=0, character=0),
+        end=_position(document, last, len(lines[last].rstrip("\r\n"))),
+    )
+
+
+def _syntax_error_range(document, error: SyntaxError) -> types.Range:
+    lines = document.lines
+    if not lines:
+        return _full_range(document)
+
+    line = min(max((error.lineno or 1) - 1, 0), len(lines) - 1)
+    text = lines[line]
+    start = min(max((error.offset or 1) - 1, 0), len(text))
+
+    end_line = min(
+        max((getattr(error, "end_lineno", None) or line + 1) - 1, line),
+        len(lines) - 1,
+    )
+    if end_line == line:
+        end = max(
+            start + 1,
+            min(
+                max((getattr(error, "end_offset", None) or start + 2) - 1, 0),
+                len(text),
+            ),
+        )
+    else:
+        end = len(lines[end_line].rstrip("\r\n"))
+
+    return types.Range(
+        start=_position(document, line, start),
+        end=_position(document, end_line, end),
+    )
+
+
+def _token_error_range(document, error: tokenize.TokenError) -> types.Range:
+    location = error.args[1] if len(error.args) > 1 else (1, 0)
+    line, character = location
+    return types.Range(
+        start=_position(document, line - 1, character),
+        end=_position(document, line - 1, character + 1),
+    )
+
+
+def _publish_diagnostics(ls: LanguageServer, document) -> None:
+    diagnostics: list[types.Diagnostic] = []
+    try:
+        parse_ast(document.source, document.path or document.uri)
+    except SyntaxError as error:
+        diagnostics.append(
+            types.Diagnostic(
+                range=_syntax_error_range(document, error),
+                message=error.msg or "Invalid Quantar syntax",
+                severity=types.DiagnosticSeverity.Error,
+                source="quantar",
+            )
+        )
+    except tokenize.TokenError as error:
+        diagnostics.append(
+            types.Diagnostic(
+                range=_token_error_range(document, error),
+                message=error.args[0] if error.args else "Tokenizer error",
+                severity=types.DiagnosticSeverity.Error,
+                source="quantar",
+            )
+        )
+    except Exception as error:
+        diagnostics.append(
+            types.Diagnostic(
+                range=_full_range(document),
+                message=str(error),
+                severity=types.DiagnosticSeverity.Error,
+                source="quantar",
+            )
+        )
+
+    ls.text_document_publish_diagnostics(
+        types.PublishDiagnosticsParams(
+            uri=document.uri,
+            diagnostics=diagnostics,
+            version=document.version,
+        )
+    )
+
+
+@server.feature(types.TEXT_DOCUMENT_DID_OPEN)
+def did_open(ls: LanguageServer, params: types.DidOpenTextDocumentParams) -> None:
+    document = ls.workspace.get_text_document(params.text_document.uri)
+    _publish_diagnostics(ls, document)
+
+
+@server.feature(types.TEXT_DOCUMENT_DID_CHANGE)
+def did_change(ls: LanguageServer, params: types.DidChangeTextDocumentParams) -> None:
+    document = ls.workspace.get_text_document(params.text_document.uri)
+    _publish_diagnostics(ls, document)
+
+
+@server.feature(types.TEXT_DOCUMENT_DID_SAVE)
+def did_save(ls: LanguageServer, params: types.DidSaveTextDocumentParams) -> None:
+    document = ls.workspace.get_text_document(params.text_document.uri)
+    _publish_diagnostics(ls, document)
+
+
+@server.feature(
+    types.TEXT_DOCUMENT_SEMANTIC_TOKENS_FULL,
+    LEGEND,
+)
+def semantic_tokens_full(
+    ls: LanguageServer, params: types.SemanticTokensParams
+) -> types.SemanticTokens:
+    document = ls.workspace.get_text_document(params.text_document.uri)
+    operators = list_known_operators()
+    data: list[int] = []
+
+    try:
+        tokens = tokenize_source(document.source)
+        previous_line = 0
+        previous_start = 0
+
+        for current in tokens:
+            if current.type not in (token.OP, token.NAME):
+                continue
+            if current.string not in operators:
+                continue
+            if current.type == token.NAME and keyword.iskeyword(current.string):
+                continue
+
+            start = _position(document, current.start[0] - 1, current.start[1])
+            end = _position(document, current.end[0] - 1, current.end[1])
+            if start.line != end.line or end.character <= start.character:
+                continue
+
+            delta_line = start.line - previous_line
+            delta_start = (
+                start.character - previous_start
+                if delta_line == 0
+                else start.character
+            )
+            modifier = MODIFIER_BITS.get(operators[current.string], 0)
+
+            data.extend(
+                [
+                    delta_line,
+                    delta_start,
+                    end.character - start.character,
+                    0,
+                    modifier,
+                ]
+            )
+            previous_line = start.line
+            previous_start = start.character
+    except (SyntaxError, tokenize.TokenError, IndentationError):
+        return types.SemanticTokens(data=[])
+
+    return types.SemanticTokens(data=data)
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO, stream=sys.stderr)
+    _load_default_operators()
+    _load_configured_operators()
+    server.start_io()
+
+
+if __name__ == "__main__":
+    main()