diraclang 0.1.0__py3-none-any.whl

dirac/__init__.py

@@ -0,0 +1,48 @@
+"""
+DIRAC Python Runtime.
+
+A Python-native port of the DIRAC language runtime (reference: dirac-lang on
+npm / the Node.js implementation in the sibling `dirac` repo).
+
+Usage:
+    from dirac import execute
+    output = execute('<dirac><output>Hello, DIRAC!</output></dirac>')
+
+    # Bra-ket notation is also supported:
+    output = execute('|output>Hello, DIRAC!', fmt="braket")
+"""
+
+from .runtime.braket_parser import BraKetParser
+from .runtime.interpreter import integrate
+from .runtime.parser import DiracParser
+from .runtime.session import create_session, get_output
+from .types import DiracElement, DiracSession
+
+__all__ = [
+    "execute",
+    "DiracParser",
+    "BraKetParser",
+    "DiracSession",
+    "DiracElement",
+    "create_session",
+]
+
+
+def execute(source: str, debug: bool = False, fmt: str = "xml") -> str:
+    """
+    Parse and execute DIRAC source code, returning the captured output.
+
+    fmt: "xml" (default, `.di` syntax) or "braket" (`.bk` syntax).
+    """
+    if fmt == "braket":
+        source = BraKetParser().parse(source)
+    elif fmt != "xml":
+        raise ValueError(f"Unknown format: {fmt!r}. Use 'xml' or 'braket'.")
+
+    parser = DiracParser()
+    session = create_session(debug=debug)
+
+    ast = parser.parse(source)
+    integrate(session, ast)
+
+    return get_output(session)

dirac/cli.py

@@ -0,0 +1,39 @@
+"""
+Command-line interface for the DIRAC Python runtime.
+Mirrors dirac/src/cli.ts (single-file execution mode only, for now).
+"""
+
+import argparse
+import sys
+
+from . import execute
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="paul", description="Run a DIRAC (.di or .bk) script.")
+    parser.add_argument("file", help="Path to a .di (XML) or .bk (bra-ket) file to execute")
+    parser.add_argument(
+        "--format",
+        choices=["xml", "braket"],
+        default=None,
+        help="Force the source format instead of auto-detecting from the file extension",
+    )
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging")
+    args = parser.parse_args()
+
+    with open(args.file, "r", encoding="utf-8") as f:
+        source = f.read()
+
+    fmt = args.format or ("braket" if args.file.endswith(".bk") else "xml")
+
+    try:
+        output = execute(source, debug=args.debug, fmt=fmt)
+    except Exception as exc:  # noqa: BLE001 - surface runtime errors to the CLI user
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    print(output, end="")
+
+
+if __name__ == "__main__":
+    main()

dirac/runtime/braket_parser.py

@@ -0,0 +1,281 @@
+"""
+Bra-Ket Parser - converts bra-ket notation to XML.
+Mirrors dirac/src/runtime/braket-parser.ts from the Node.js reference
+implementation.
+
+Syntax:
+  - Bra (subroutine): <name|  ... defines a subroutine
+  - Ket (everything else): |tag attrs>  ... can have children/content
+  - Indentation defines scope (2 spaces per level), same convention as
+    Python itself - which is the whole point of porting this to Python:
+    a Python code block embedded in a ket's body (e.g. inside <eval>)
+    keeps its own relative indentation intact, because each line's
+    indentation is measured in absolute spaces and re-expressed as
+    2 * (spaces // 2) - an identity transform for any evenly-indented
+    code (2/4/8-space Python or JS, which is effectively all real code).
+
+Examples:
+    |output>Hello World          ->  <output>Hello World</output>
+    |variable name=x>            ->  <variable name="x"/>
+    <add|                        ->  <subroutine name="add">
+      |output>test               ->    <output>test</output>
+                                  ->  </subroutine>
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+_BRA_TAG_RE = re.compile(r"^<([a-zA-Z_][a-zA-Z0-9_-]*)\s*")
+_KET_RE = re.compile(r"^\|([a-zA-Z_][a-zA-Z0-9_-]*)\s*([^>]*?)>\s*(.*)")
+_INLINE_KET_RE = re.compile(r"\|([a-zA-Z_][a-zA-Z0-9_-]*)\s*([^>]*?)>")
+_ATTR_RE = re.compile(r"^([a-zA-Z_][a-zA-Z0-9_-]*)=(.+)$")
+
+_RESERVED_BRA_ATTRS = {"description", "extends", "visible", "lang"}
+
+
+@dataclass
+class _Line:
+    indent: int
+    type: str  # 'bra' | 'ket' | 'text' | 'empty'
+    tag: Optional[str] = None
+    attrs: Optional[str] = None
+    text: Optional[str] = None
+    raw: str = ""
+
+
+class BraKetParser:
+    """Parses bra-ket notation and compiles it to a DIRAC-ROOT-free XML string."""
+
+    def __init__(self) -> None:
+        self._lines: list = []
+        self._current_line = 0
+
+    def parse(self, source: str) -> str:
+        self._lines = source.split("\n")
+        self._current_line = 0
+
+        xml = ["<dirac>"]
+        self._parse_block(xml, -1)
+        xml.append("</dirac>")
+
+        return "\n".join(xml)
+
+    # -- Block/line parsing ------------------------------------------------
+
+    def _parse_block(self, output: list, parent_indent: int) -> None:
+        while self._current_line < len(self._lines):
+            line = self._parse_line(self._lines[self._current_line])
+
+            if line.type == "empty":
+                self._current_line += 1
+                continue
+
+            if line.indent <= parent_indent:
+                break
+
+            if line.type == "bra":
+                attrs = f" {self._convert_bra_attributes(line.attrs)}" if line.attrs else ""
+                output.append(f"{'  ' * line.indent}<subroutine name=\"{line.tag}\"{attrs}>")
+                self._current_line += 1
+                self._parse_block(output, line.indent)
+                output.append(f"{'  ' * line.indent}</subroutine>")
+                continue
+
+            if line.type == "ket":
+                indent_str = "  " * line.indent
+                attrs = f" {self._convert_ket_attributes(line.attrs, line.tag or '')}" if line.attrs else ""
+
+                next_line = (
+                    self._parse_line(self._lines[self._current_line + 1])
+                    if self._current_line + 1 < len(self._lines)
+                    else None
+                )
+
+                if next_line is not None and next_line.indent > line.indent and next_line.type != "empty":
+                    output.append(f"{indent_str}<{line.tag}{attrs}>")
+                    self._current_line += 1
+                    self._parse_block(output, line.indent)
+                    output.append(f"{indent_str}</{line.tag}>")
+                else:
+                    if line.text:
+                        content = self._convert_inline_kets(line.text)
+                        output.append(f"{indent_str}<{line.tag}{attrs}>{content}</{line.tag}>")
+                    else:
+                        output.append(f"{indent_str}<{line.tag}{attrs}/>")
+                    self._current_line += 1
+                continue
+
+            if line.type == "text":
+                indent_str = "  " * line.indent
+                content = self._convert_inline_kets(line.text or "")
+                output.append(f"{indent_str}{content}")
+                self._current_line += 1
+                continue
+
+    def _parse_line(self, raw: str) -> _Line:
+        match = re.match(r"^(\s*)(.*)", raw)
+        indent = len(match.group(1)) // 2 if match else 0
+        content = match.group(2) if match else ""
+
+        if not content.strip():
+            return _Line(indent=indent, type="empty", raw=raw)
+
+        if content.startswith("#"):
+            return _Line(indent=indent, type="empty", raw=raw)
+
+        # Bra: <name| or <name attrs|
+        if content.startswith("<") and content.endswith("|"):
+            tag_match = _BRA_TAG_RE.match(content)
+            if tag_match:
+                tag_name = tag_match.group(1)
+                after_tag = content[tag_match.end() : -1]  # strip trailing |
+                return _Line(
+                    indent=indent,
+                    type="bra",
+                    tag=tag_name,
+                    attrs=after_tag.strip() or None,
+                    raw=raw,
+                )
+
+        # Ket: |tag> or |tag attrs> or |tag>text
+        ket_match = _KET_RE.match(content)
+        if ket_match:
+            return _Line(
+                indent=indent,
+                type="ket",
+                tag=ket_match.group(1),
+                attrs=ket_match.group(2).strip() or None,
+                text=ket_match.group(3) or None,
+                raw=raw,
+            )
+
+        return _Line(indent=indent, type="text", text=content, raw=raw)
+
+    # -- Attribute conversion ------------------------------------------------
+
+    def _parse_attribute_parts(self, attrs: str) -> list:
+        parts: list = []
+        current = ""
+        in_quotes = False
+        quote_char = ""
+
+        for i, char in enumerate(attrs):
+            if char in ("\"", "'") and (i == 0 or attrs[i - 1] != "\\"):
+                if not in_quotes:
+                    in_quotes = True
+                    quote_char = char
+                    current += char
+                elif char == quote_char:
+                    in_quotes = False
+                    current += char
+                else:
+                    current += char
+            elif char == " " and not in_quotes:
+                if current.strip():
+                    parts.append(current.strip())
+                    current = ""
+            else:
+                current += char
+
+        if current.strip():
+            parts.append(current.strip())
+
+        return parts
+
+    def _quote_value(self, value: str) -> str:
+        if (value.startswith('"') and value.endswith('"')) or (
+            value.startswith("'") and value.endswith("'")
+        ):
+            return value
+        return f'"{value}"'
+
+    def _convert_attributes(self, attrs: str) -> str:
+        if not attrs:
+            return ""
+
+        parts = self._parse_attribute_parts(attrs)
+        converted = []
+        for part in parts:
+            match = _ATTR_RE.match(part)
+            if not match:
+                converted.append(part)
+                continue
+            name, value = match.group(1), match.group(2)
+            if (value.startswith('"') and value.endswith('"')) or (
+                value.startswith("'") and value.endswith("'")
+            ):
+                converted.append(f"{name}={value}")
+            else:
+                converted.append(f'{name}="{value}"')
+        return " ".join(converted)
+
+    def _convert_bra_attributes(self, attrs: Optional[str]) -> str:
+        if not attrs:
+            return ""
+
+        parts = self._parse_attribute_parts(attrs)
+        converted = []
+        for part in parts:
+            match = _ATTR_RE.match(part)
+            if not match:
+                converted.append(part)
+                continue
+            name, value = match.group(1), match.group(2)
+            is_reserved = name in _RESERVED_BRA_ATTRS
+            attr_name = name if is_reserved else f"param-{name}"
+            if (value.startswith('"') and value.endswith('"')) or (
+                value.startswith("'") and value.endswith("'")
+            ):
+                converted.append(f"{attr_name}={value}")
+            else:
+                converted.append(f'{attr_name}="{value}"')
+        return " ".join(converted)
+
+    def _convert_ket_attributes(self, attrs: Optional[str], tag_name: str) -> str:
+        if not attrs:
+            return ""
+
+        parts = self._parse_attribute_parts(attrs)
+        has_positional = any("=" not in part for part in parts)
+
+        if not has_positional:
+            return self._convert_attributes(attrs)
+
+        positional_index = 0
+        converted = []
+        for part in parts:
+            match = _ATTR_RE.match(part)
+            if match:
+                name, value = match.group(1), match.group(2)
+                converted.append(f"{name}={self._quote_value(value)}")
+            else:
+                converted.append(f"_positional-{positional_index}={self._quote_value(part)}")
+                positional_index += 1
+        return " ".join(converted)
+
+    def _escape_xml(self, text: str) -> str:
+        return (
+            text.replace("&", "&amp;")  # must be first
+            .replace("<", "&lt;")
+            .replace(">", "&gt;")
+        )
+
+    def _convert_inline_kets(self, text: str) -> str:
+        parts = []
+        last_index = 0
+
+        for match in _INLINE_KET_RE.finditer(text):
+            if match.start() > last_index:
+                parts.append(self._escape_xml(text[last_index : match.start()]))
+
+            tag, attrs = match.group(1), match.group(2)
+            attr_str = f" {self._convert_attributes(attrs.strip())}" if attrs.strip() else ""
+            parts.append(f"<{tag}{attr_str}/>")
+
+            last_index = match.end()
+
+        if last_index < len(text):
+            parts.append(self._escape_xml(text[last_index:]))
+
+        return "".join(parts)

dirac/runtime/interpreter.py

@@ -0,0 +1,134 @@
+"""
+Core interpreter - dispatches DiracElement nodes to tag handlers.
+Mirrors dirac/src/runtime/interpreter.ts from the Node.js reference implementation.
+"""
+
+from ..types import DiracElement, DiracSession
+from .session import emit, substitute_attribute
+from ..tags.assign import execute_assign
+from ..tags.break_tag import execute_break
+from ..tags.call import execute_call
+from ..tags.defvar import execute_defvar
+from ..tags.eval_tag import execute_eval
+from ..tags.foreach import execute_foreach
+from ..tags.if_tag import execute_if
+from ..tags.import_tag import execute_import
+from ..tags.input_tag import execute_input
+from ..tags.llm_tag import execute_llm
+from ..tags.loop import execute_loop
+from ..tags.output import execute_output
+from ..tags.parameters_tag import execute_parameters
+from ..tags.return_tag import execute_return
+from ..tags.subroutine import execute_subroutine
+from ..tags.system import execute_system
+from ..tags.test_if import execute_test_if
+from ..tags.variable import execute_variable
+
+# Tags whose body is a direct-call to a registered subroutine (anything not
+# in this set of built-in tag names).
+_BUILTIN_TAGS = {
+    "dirac-root",
+    "dirac",
+    "defvar",
+    "variable",
+    "assign",
+    "output",
+    "subroutine",
+    "call",
+    "parameters",
+    "loop",
+    "foreach",
+    "break",
+    "if",
+    "test-if",
+    "eval",
+    "python",
+    "system",
+    "input",
+    "return",
+    "import",
+    "llm",
+}
+
+
+def integrate(session: DiracSession, element: DiracElement) -> None:
+    """Execute a single DiracElement node."""
+    # Text nodes
+    if element.text and not element.tag:
+        emit(session, substitute_attribute(session, element.text))
+        return
+
+    # Control flow: stop execution if return or break has been signaled.
+    if session.is_return or session.is_break:
+        return
+
+    tag = element.tag.lower()
+
+    if tag in ("dirac-root", "dirac"):
+        integrate_children(session, element)
+        return
+    if tag == "defvar":
+        execute_defvar(session, element)
+        return
+    if tag == "variable":
+        execute_variable(session, element)
+        return
+    if tag == "assign":
+        execute_assign(session, element)
+        return
+    if tag == "output":
+        execute_output(session, element)
+        return
+    if tag == "subroutine":
+        execute_subroutine(session, element)
+        return
+    if tag == "call":
+        execute_call(session, element)
+        return
+    if tag == "parameters":
+        execute_parameters(session, element)
+        return
+    if tag == "loop":
+        execute_loop(session, element)
+        return
+    if tag == "foreach":
+        execute_foreach(session, element)
+        return
+    if tag == "break":
+        execute_break(session, element)
+        return
+    if tag == "if":
+        execute_if(session, element)
+        return
+    if tag == "test-if":
+        execute_test_if(session, element)
+        return
+    if tag in ("eval", "python"):
+        execute_eval(session, element)
+        return
+    if tag == "system":
+        execute_system(session, element)
+        return
+    if tag == "input":
+        execute_input(session, element)
+        return
+    if tag == "return":
+        execute_return(session, element)
+        return
+    if tag == "import":
+        execute_import(session, element)
+        return
+    if tag == "llm":
+        execute_llm(session, element)
+        return
+
+    # Not a built-in tag - treat as a direct subroutine call, e.g. <greet name="Alice" />
+    execute_call(session, element)
+
+
+def integrate_children(session: DiracSession, element: DiracElement) -> None:
+    """Execute all children of an element in order."""
+    for child in element.children:
+        integrate(session, child)
+        if session.is_return or session.is_break:
+            break

dirac/runtime/parser.py

@@ -0,0 +1,51 @@
+"""
+XML Parser for DIRAC (.di files).
+Mirrors dirac/src/runtime/parser.ts (which uses fast-xml-parser) using the
+Python standard library's xml.etree.ElementTree.
+"""
+
+import re
+import xml.etree.ElementTree as ET
+
+from ..types import DiracElement
+
+_SHEBANG_RE = re.compile(r"^#!.*\n")
+
+
+class DiracParser:
+    """Parses DIRAC XML source into a DiracElement tree."""
+
+    def parse(self, source: str) -> DiracElement:
+        # Strip shebang line if present
+        if source.startswith("#!"):
+            source = _SHEBANG_RE.sub("", source, count=1)
+
+        # Always wrap in DIRAC-ROOT to ensure valid XML with a single root.
+        # This allows files with comments, multiple top-level elements, or no
+        # root element at all (matches the Node.js parser's behavior).
+        wrapped = f"<DIRAC-ROOT>\n{source}\n</DIRAC-ROOT>"
+
+        try:
+            root = ET.fromstring(wrapped)
+        except ET.ParseError as exc:
+            raise ValueError(f"Failed to parse DIRAC XML: {exc}") from exc
+
+        return self._convert(root)
+
+    def _convert(self, node: ET.Element) -> DiracElement:
+        element = DiracElement(tag=node.tag, attributes=dict(node.attrib), children=[])
+
+        # Leading text (before the first child, if any)
+        if node.text:
+            element.children.append(DiracElement(tag="", text=node.text))
+            element.text = node.text
+
+        for child in node:
+            element.children.append(self._convert(child))
+
+            # Tail text (text following this child's closing tag)
+            if child.tail:
+                element.children.append(DiracElement(tag="", text=child.tail))
+                element.text = (element.text or "") + child.tail
+
+        return element