rosettakit 0.2.0__py3-none-any.whl

rosettakit/__init__.py

@@ -0,0 +1,5 @@
+"""Typed EDA script builders."""
+
+from rosettakit import cmdfile, tcl
+
+__all__ = ["cmdfile", "tcl"]

rosettakit/cmdfile.py

@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum
+from typing import TypeAlias
+
+from rosettakit.diagnostics import Diagnostic
+from rosettakit.errors import BuildError, UnsafeRawError, ValidationError
+
+
+CommandFileValue: TypeAlias = object
+
+
+class ValueType(Enum):
+    """Value category used for command-file validation diagnostics."""
+
+    SCALAR = "scalar"
+    PATH = "path"
+
+
+class ValueQuoting(Enum):
+    """Policy used to validate and render command-file option values."""
+
+    TCL_WORD = "tcl-word"
+    PLAIN_UNQUOTED = "plain-unquoted"
+
+
+@dataclass(frozen=True)
+class CommandFileDialect:
+    """Named command-file dialect describing how option values are represented."""
+
+    name: str
+    value_quoting: ValueQuoting
+
+
+TCL_WORD_DIALECT = CommandFileDialect(
+    name="tcl-word",
+    value_quoting=ValueQuoting.TCL_WORD,
+)
+"""Default command-file dialect using Tcl-word-like quoting for option values."""
+
+PLAIN_DIALECT = CommandFileDialect(
+    name="plain",
+    value_quoting=ValueQuoting.PLAIN_UNQUOTED,
+)
+"""Whitespace-delimited command-file dialect that rejects values needing quoting."""
+
+
+@dataclass(frozen=True)
+class Comment:
+    """A command-file comment node."""
+
+    text: str
+    origin: str | None = None
+
+
+@dataclass(frozen=True)
+class BlankLine:
+    """A blank command-file output line."""
+
+    origin: str | None = None
+
+
+@dataclass(frozen=True)
+class Flag:
+    """A command-file flag node rendered without a value."""
+
+    name: str
+    origin: str | None = None
+
+
+@dataclass(frozen=True)
+class Option:
+    """A command-file option node rendered with one value."""
+
+    name: str
+    value: CommandFileValue
+    value_type: ValueType
+    omit_empty: bool
+    origin: str | None = None
+
+
+@dataclass(frozen=True)
+class RawLine:
+    """A raw command-file line that requires explicit build opt-in."""
+
+    text: str
+    origin: str | None = None
+
+
+CommandFileNode: TypeAlias = Comment | BlankLine | Flag | Option | RawLine
+
+
+class CommandFile:
+    """Mutable command-file document that preserves insertion order."""
+
+    def __init__(
+        self,
+        *,
+        prefix: str = "-",
+        dialect: CommandFileDialect = TCL_WORD_DIALECT,
+    ) -> None:
+        """Create an empty command-file document.
+
+        `prefix` is prepended to flags and option names. Use `prefix=""` for
+        command-like env files that do not use dashed option names. `dialect`
+        controls validation and rendering for option values.
+        """
+        self.prefix = prefix
+        self.dialect = dialect
+        self._nodes: list[CommandFileNode] = []
+
+    @property
+    def nodes(self) -> tuple[CommandFileNode, ...]:
+        """Return an immutable snapshot of command-file nodes."""
+        return tuple(self._nodes)
+
+    def comment(self, text: str, *, origin: str | None = None) -> None:
+        """Append one or more comment lines.
+
+        Newline-separated text is emitted as separate comment lines. `origin` is
+        attached to diagnostics produced from this node.
+        """
+        self._nodes.append(Comment(text, origin))
+
+    def blank_line(self, *, origin: str | None = None) -> None:
+        """Append a blank line to the command file."""
+        self._nodes.append(BlankLine(origin))
+
+    def flag(self, name: str, *, origin: str | None = None) -> None:
+        """Append a flag line such as `-useOpenSTA`."""
+        self._nodes.append(Flag(name, origin))
+
+    def option(
+        self,
+        name: str,
+        value: CommandFileValue,
+        *,
+        value_type: ValueType = ValueType.SCALAR,
+        omit_empty: bool = False,
+        origin: str | None = None,
+    ) -> None:
+        """Append one option line with a dialect-rendered value.
+
+        Set `value_type=ValueType.PATH` for filesystem paths so validation can
+        report empty paths and path quoting diagnostics. `omit_empty=True`
+        suppresses the line when the value is an empty string.
+        """
+        self._nodes.append(Option(name, value, value_type, omit_empty, origin))
+
+    def options(
+        self,
+        name: str,
+        values: Iterable[CommandFileValue],
+        *,
+        value_type: ValueType = ValueType.SCALAR,
+        omit_empty: bool = False,
+        origin: str | None = None,
+    ) -> None:
+        """Append one option line for each value in `values`."""
+        for value in values:
+            self.option(
+                name,
+                value,
+                value_type=value_type,
+                omit_empty=omit_empty,
+                origin=origin,
+            )
+
+    def raw_line(self, text: str, *, origin: str | None = None) -> None:
+        """Append a raw command-file line that bypasses escaping.
+
+        Raw lines are an escape hatch for hand-written output. Builds fail on
+        raw content unless `allow_unsafe_raw=True` is passed.
+        """
+        self._nodes.append(RawLine(text, origin))
+
+    def validate(self) -> list[Diagnostic]:
+        """Return diagnostics for this command file without rendering text."""
+        return CommandFileBuilder().validate(self)
+
+    def build(self, *, allow_unsafe_raw: bool = False) -> str:
+        """Validate and render this command file as text.
+
+        Raises `ValidationError` for blocking diagnostics and `UnsafeRawError`
+        when raw content is present without `allow_unsafe_raw=True`.
+        """
+        return CommandFileBuilder(allow_unsafe_raw=allow_unsafe_raw).build(self)
+
+
+class CommandFileBuilder:
+    """Renderer and validator for RosettaKit command-file documents."""
+
+    backend = "command-file"
+
+    def __init__(self, *, allow_unsafe_raw: bool = False) -> None:
+        """Create a command-file builder with the requested raw-content policy."""
+        self.allow_unsafe_raw = allow_unsafe_raw
+
+    def build(self, document: CommandFile) -> str:
+        """Validate and render a `CommandFile` into text."""
+        diagnostics = self.validate(document)
+        raw_diagnostics = [item for item in diagnostics if item.code == "unsafe-raw"]
+        blocking = [item for item in diagnostics if item.code not in {"unsafe-raw", "quoted-path"}]
+        if raw_diagnostics and not self.allow_unsafe_raw:
+            raise UnsafeRawError(self.backend, raw_diagnostics)
+        if blocking:
+            raise ValidationError(self.backend, blocking)
+        return "".join(
+            self._render_node(document.prefix, document.dialect, node) for node in document.nodes
+        )
+
+    def validate(self, document: CommandFile) -> list[Diagnostic]:
+        """Return diagnostics for a `CommandFile` without rendering text."""
+        diagnostics: list[Diagnostic] = []
+        if not _is_supported_dialect(document.dialect):
+            diagnostics.append(
+                Diagnostic(
+                    "unsupported-command-file-dialect",
+                    f"unsupported command-file dialect: {document.dialect.name}",
+                )
+            )
+        for node in document.nodes:
+            diagnostics.extend(self._validate_node(document.dialect, node))
+        return diagnostics
+
+    def _render_node(
+        self,
+        prefix: str,
+        dialect: CommandFileDialect,
+        node: CommandFileNode,
+    ) -> str:
+        if isinstance(node, Comment):
+            return "".join(f"# {line}\n" for line in _comment_lines(node.text))
+        if isinstance(node, BlankLine):
+            return "\n"
+        if isinstance(node, Flag):
+            return f"{prefix}{node.name}\n"
+        if isinstance(node, Option):
+            if node.omit_empty and node.value == "":
+                return ""
+            return f"{prefix}{node.name} {self._render_option_value(dialect, node.value)}\n"
+        if isinstance(node, RawLine):
+            return f"{node.text}\n"
+        raise BuildError(f"unsupported command-file node: {node!r}")
+
+    def _render_option_value(self, dialect: CommandFileDialect, value: object) -> str:
+        text = str(value)
+        if dialect.value_quoting is ValueQuoting.TCL_WORD:
+            return _quote_word(text)
+        if dialect.value_quoting is ValueQuoting.PLAIN_UNQUOTED:
+            return text
+        raise BuildError(f"unsupported command-file dialect: {dialect.name}")
+
+    def _validate_node(
+        self,
+        dialect: CommandFileDialect,
+        node: CommandFileNode,
+    ) -> list[Diagnostic]:
+        diagnostics: list[Diagnostic] = []
+        if isinstance(node, Flag):
+            if not node.name:
+                diagnostics.append(
+                    Diagnostic("empty-option-name", "flag name is required", node.origin)
+                )
+        elif isinstance(node, Option):
+            diagnostics.extend(self._validate_option(dialect, node))
+        elif isinstance(node, RawLine):
+            diagnostics.append(
+                Diagnostic(
+                    "unsafe-raw",
+                    "raw command-file line requires explicit opt-in",
+                    node.origin,
+                )
+            )
+        elif isinstance(node, (Comment, BlankLine)):
+            pass
+        else:
+            diagnostics.append(
+                Diagnostic(
+                    "unsupported-node",
+                    f"unsupported command-file node {type(node).__name__}",
+                )
+            )
+        return diagnostics
+
+    def _validate_option(
+        self,
+        dialect: CommandFileDialect,
+        node: Option,
+    ) -> list[Diagnostic]:
+        diagnostics: list[Diagnostic] = []
+        text = str(node.value)
+        if not node.name:
+            diagnostics.append(
+                Diagnostic("empty-option-name", "option name is required", node.origin)
+            )
+        if _has_line_break(text):
+            diagnostics.append(
+                Diagnostic(
+                    "line-break-in-value",
+                    "command-file values cannot contain line breaks",
+                    node.origin,
+                )
+            )
+        if node.value_type is ValueType.PATH and node.value == "" and not node.omit_empty:
+            diagnostics.append(Diagnostic("empty-path", "path value is required", node.origin))
+        if dialect.value_quoting is ValueQuoting.TCL_WORD:
+            diagnostics.extend(_validate_tcl_word_option(node, text))
+        elif dialect.value_quoting is ValueQuoting.PLAIN_UNQUOTED:
+            diagnostics.extend(_validate_plain_option(node, text))
+        return diagnostics
+
+
+def _quote_word(text: str) -> str:
+    if text == "":
+        return "{}"
+    if not _needs_quoting(text):
+        return text
+    if "{" not in text and "}" not in text and "\n" not in text and "\r" not in text:
+        return "{" + text + "}"
+    return "".join(_escape_word_char(char) for char in text)
+
+
+def _needs_quoting(text: str) -> bool:
+    return text == "" or any(char.isspace() or char in "{}[]$;\\\"" for char in text)
+
+
+def _escape_word_char(char: str) -> str:
+    replacements = {
+        " ": "\\ ",
+        "\t": "\\t",
+        "\r": "\\r",
+        "\n": "\\n",
+        "\\": "\\\\",
+        "{": "\\{",
+        "}": "\\}",
+        "[": "\\[",
+        "]": "\\]",
+        "$": "\\$",
+        ";": "\\;",
+        '"': '\\"',
+    }
+    return replacements.get(char, char)
+
+
+def _has_line_break(text: str) -> bool:
+    return "\n" in text or "\r" in text
+
+
+def _comment_lines(text: str) -> list[str]:
+    return text.splitlines() or [""]
+
+
+def _validate_tcl_word_option(node: Option, text: str) -> list[Diagnostic]:
+    if node.value_type is ValueType.PATH and text != "" and _needs_quoting(text):
+        return [Diagnostic("quoted-path", "path requires command-file quoting", node.origin)]
+    return []
+
+
+def _validate_plain_option(node: Option, text: str) -> list[Diagnostic]:
+    if node.omit_empty and node.value == "":
+        return []
+    if node.value_type is ValueType.SCALAR and text == "":
+        return [
+            Diagnostic(
+                "empty-unquoted-value",
+                "empty values cannot be represented as plain whitespace-delimited tokens",
+                node.origin,
+            )
+        ]
+    if text != "" and not _has_line_break(text) and _needs_quoting(text):
+        return [
+            Diagnostic(
+                "unquoted-value-needs-quoting",
+                "plain command-file values cannot contain whitespace or quoting characters",
+                node.origin,
+            )
+        ]
+    return []
+
+
+def _is_supported_dialect(dialect: CommandFileDialect) -> bool:
+    return dialect.value_quoting in {
+        ValueQuoting.TCL_WORD,
+        ValueQuoting.PLAIN_UNQUOTED,
+    }

rosettakit/diagnostics.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    code: str
+    message: str
+    origin: str | None = None

rosettakit/errors.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from rosettakit.diagnostics import Diagnostic
+
+
+class ScriptDslError(Exception):
+    """Base class for RosettaKit script DSL errors."""
+
+
+class ValidationError(ScriptDslError):
+    def __init__(self, backend: str, diagnostics: Sequence[Diagnostic]) -> None:
+        self.backend = backend
+        self.diagnostics = tuple(diagnostics)
+        details = "; ".join(_format_diagnostic(item) for item in self.diagnostics)
+        super().__init__(f"{backend} validation failed: {details}")
+
+
+class BuildError(ScriptDslError):
+    """Raised when a builder cannot render a document."""
+
+
+class UnsafeRawError(ValidationError):
+    def __init__(self, backend: str, diagnostics: Sequence[Diagnostic]) -> None:
+        super().__init__(backend, diagnostics)
+
+
+def _format_diagnostic(diagnostic: Diagnostic) -> str:
+    if diagnostic.origin:
+        return f"{diagnostic.code} at {diagnostic.origin}: {diagnostic.message}"
+    return f"{diagnostic.code}: {diagnostic.message}"

rosettakit/tcl.py

@@ -0,0 +1,499 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import TypeAlias
+
+from rosettakit.diagnostics import Diagnostic
+from rosettakit.errors import BuildError, UnsafeRawError, ValidationError
+
+
+TclInputValue: TypeAlias = object
+
+
+@dataclass(frozen=True)
+class Scalar:
+    """A scalar Tcl value rendered as one safely quoted word."""
+
+    value: TclInputValue
+
+
+@dataclass(frozen=True)
+class PathValue:
+    """A Tcl value that represents a filesystem path."""
+
+    value: str
+
+
+@dataclass(frozen=True)
+class ListValue:
+    """A Tcl list value rendered with the Tcl `list` command."""
+
+    values: tuple[TclInputValue, ...]
+
+
+@dataclass(frozen=True)
+class VarRef:
+    """A reference to a Tcl variable rendered as `$name`."""
+
+    name: str
+
+
+@dataclass(frozen=True)
+class Expr:
+    """A Tcl expression rendered as `[expr {...}]`."""
+
+    expression: str
+
+
+@dataclass(frozen=True)
+class CommandSubstitution:
+    """A Tcl command substitution rendered as `[command arg ...]`."""
+
+    command: str
+    args: tuple[TclInputValue, ...]
+
+
+@dataclass(frozen=True)
+class Raw:
+    """Raw Tcl text that bypasses escaping and requires explicit build opt-in."""
+
+    text: str
+
+
+TclValue: TypeAlias = Scalar | PathValue | ListValue | VarRef | Expr | CommandSubstitution | Raw
+
+
+@dataclass(frozen=True)
+class Condition:
+    """A rendered Tcl condition plus diagnostics for values used to build it."""
+
+    text: str
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+
+@dataclass(frozen=True)
+class Comment:
+    """A Tcl comment node."""
+
+    text: str
+    origin: str | None = None
+
+
+@dataclass(frozen=True)
+class BlankLine:
+    """A blank Tcl output line."""
+
+    origin: str | None = None
+
+
+@dataclass(frozen=True)
+class Set:
+    """A Tcl `set` command node."""
+
+    name: str
+    value: TclValue
+    scalar_api: bool = True
+    origin: str | None = None
+
+
+@dataclass(frozen=True)
+class Command:
+    """A generic Tcl command node."""
+
+    name: str
+    args: tuple[TclValue, ...]
+    origin: str | None = None
+
+
+@dataclass(frozen=True)
+class If:
+    """A Tcl `if` node with a nested body."""
+
+    condition: Condition
+    body: list[TclNode]
+    origin: str | None = None
+
+
+@dataclass(frozen=True)
+class RawLine:
+    """A raw Tcl line that bypasses escaping and requires explicit build opt-in."""
+
+    text: str
+    origin: str | None = None
+
+
+TclNode: TypeAlias = Comment | BlankLine | Set | Command | If | RawLine
+
+
+def word(value: TclInputValue) -> Scalar:
+    """Create a scalar Tcl word that RosettaKit quotes safely when rendered.
+
+    Use this for single Tcl values passed to `Script.set` or command arguments.
+    Non-string Python values are converted with `str(...)` during rendering.
+    """
+    return Scalar(value)
+
+
+def path(value: str) -> PathValue:
+    """Create a filesystem path value for Tcl output.
+
+    Path values render as one safely quoted Tcl word and participate in path
+    diagnostics such as empty-path and quoted-path warnings.
+    """
+    return PathValue(value)
+
+
+def list_value(values: Iterable[TclInputValue]) -> ListValue:
+    """Create a Tcl list value rendered as `[list item ...]`.
+
+    Prefer `Script.set_list` when assigning a variable to a Tcl list. This helper
+    is useful when a list must be passed as a value object.
+    """
+    return ListValue(tuple(values))
+
+
+def var(name: str) -> VarRef:
+    """Reference an existing Tcl variable as `$name`.
+
+    The variable name is inserted without quoting; empty names are reported by
+    validation and rejected during rendering.
+    """
+    return VarRef(name)
+
+
+def expr(expression: str) -> Expr:
+    """Create a Tcl expression substitution rendered as `[expr {...}]`.
+
+    The expression text is inserted into the braced Tcl expression body. Pass
+    trusted expression text rather than unescaped user input.
+    """
+    return Expr(expression)
+
+
+def call(command: str, *args: TclInputValue) -> CommandSubstitution:
+    """Create a Tcl command substitution rendered as `[command arg ...]`.
+
+    Arguments are rendered through RosettaKit value quoting. The command name is
+    used as provided, so keep it controlled by the caller.
+    """
+    return CommandSubstitution(command, args)
+
+
+def raw(text: str) -> Raw:
+    """Create raw Tcl value text that bypasses all escaping.
+
+    Raw values are an escape hatch for hand-written Tcl snippets. Builds fail on
+    raw content unless `allow_unsafe_raw=True` is passed.
+    """
+    return Raw(text)
+
+
+def file_isdirectory(value: TclInputValue) -> Condition:
+    """Create a Tcl condition for `[file isdirectory value]`.
+
+    The value is rendered with RosettaKit quoting and any value diagnostics are
+    carried into the condition for later validation.
+    """
+    diagnostics = tuple(_validate_value(value, origin=None, scalar_api=False))
+    return Condition(f"[file isdirectory {TclBuilder().render_value(value)}]", diagnostics)
+
+
+class Script:
+    """Mutable Tcl script document that preserves insertion order."""
+
+    def __init__(self) -> None:
+        """Create an empty Tcl script document."""
+        self._nodes: list[TclNode] = []
+        self._stack: list[list[TclNode]] = [self._nodes]
+
+    @property
+    def nodes(self) -> tuple[TclNode, ...]:
+        """Return an immutable snapshot of top-level Tcl nodes."""
+        return tuple(self._nodes)
+
+    def comment(self, text: str, *, origin: str | None = None) -> None:
+        """Append one or more Tcl comment lines.
+
+        Newline-separated text is emitted as separate comment lines. `origin` is
+        attached to diagnostics produced from this node.
+        """
+        self._current().append(Comment(text, origin))
+
+    def blank_line(self, *, origin: str | None = None) -> None:
+        """Append a blank line to the script."""
+        self._current().append(BlankLine(origin))
+
+    def set(self, name: str, value: TclInputValue, *, origin: str | None = None) -> None:
+        """Append a Tcl `set name value` command.
+
+        Scalar values are quoted as one Tcl word. Use `set_list` for Tcl lists so
+        validation can distinguish list assignment from scalar assignment.
+        """
+        self._current().append(Set(name, _coerce_value(value), True, origin))
+
+    def set_path(self, name: str, value: str, *, origin: str | None = None) -> None:
+        """Append a Tcl `set` command whose value represents a filesystem path."""
+        self.set(name, path(value), origin=origin)
+
+    def set_list(
+        self,
+        name: str,
+        values: Iterable[TclInputValue],
+        *,
+        origin: str | None = None,
+    ) -> None:
+        """Append a Tcl `set` command whose value is rendered as a Tcl list."""
+        self._current().append(Set(name, list_value(values), False, origin))
+
+    def set_expr(self, name: str, expression: str, *, origin: str | None = None) -> None:
+        """Append a Tcl `set` command whose value is rendered as `[expr {...}]`."""
+        self.set(name, expr(expression), origin=origin)
+
+    def command(self, name: str, *args: TclInputValue, origin: str | None = None) -> None:
+        """Append a generic Tcl command with safely rendered arguments.
+
+        The command name is emitted as provided. Each argument is converted to a
+        RosettaKit value and rendered as one Tcl word or value expression.
+        """
+        self._current().append(Command(name, tuple(_coerce_value(arg) for arg in args), origin))
+
+    def file_mkdir(self, value: TclInputValue, *, origin: str | None = None) -> None:
+        """Append `file mkdir value` with the directory value safely rendered."""
+        self.command("file", "mkdir", value, origin=origin)
+
+    @contextmanager
+    def if_not(self, condition: Condition, *, origin: str | None = None) -> Iterator[Script]:
+        """Append an `if {!(condition)}` block and yield this script for its body."""
+        body: list[TclNode] = []
+        self._current().append(
+            If(Condition(f"!({condition.text})", condition.diagnostics), body, origin)
+        )
+        self._stack.append(body)
+        try:
+            yield self
+        finally:
+            self._stack.pop()
+
+    def raw_line(self, text: str, *, origin: str | None = None) -> None:
+        """Append a raw Tcl line that bypasses escaping.
+
+        Raw lines are an escape hatch for hand-written Tcl. Builds fail on raw
+        content unless `allow_unsafe_raw=True` is passed.
+        """
+        self._current().append(RawLine(text, origin))
+
+    def validate(self) -> list[Diagnostic]:
+        """Return diagnostics for this script without rendering text."""
+        return TclBuilder().validate(self)
+
+    def build(self, *, allow_unsafe_raw: bool = False) -> str:
+        """Validate and render this script as Tcl text.
+
+        Raises `ValidationError` for blocking diagnostics and `UnsafeRawError`
+        when raw content is present without `allow_unsafe_raw=True`.
+        """
+        return TclBuilder(allow_unsafe_raw=allow_unsafe_raw).build(self)
+
+    def _current(self) -> list[TclNode]:
+        return self._stack[-1]
+
+
+class TclBuilder:
+    """Renderer and validator for RosettaKit Tcl scripts."""
+
+    backend = "tcl"
+
+    def __init__(self, *, indent: str = "    ", allow_unsafe_raw: bool = False) -> None:
+        """Create a Tcl builder with indentation and raw-content policy."""
+        self.indent = indent
+        self.allow_unsafe_raw = allow_unsafe_raw
+
+    def build(self, script: Script) -> str:
+        """Validate and render a `Script` into Tcl text."""
+        diagnostics = self.validate(script)
+        raw_diagnostics = [item for item in diagnostics if item.code == "unsafe-raw"]
+        blocking = [item for item in diagnostics if item.code not in {"unsafe-raw", "quoted-path"}]
+        if raw_diagnostics and not self.allow_unsafe_raw:
+            raise UnsafeRawError(self.backend, raw_diagnostics)
+        if blocking:
+            raise ValidationError(self.backend, blocking)
+        return "".join(self._render_node(node, level=0) for node in script.nodes)
+
+    def validate(self, script: Script) -> list[Diagnostic]:
+        """Return diagnostics for a `Script` without rendering text."""
+        diagnostics: list[Diagnostic] = []
+        for node in script.nodes:
+            diagnostics.extend(self._validate_node(node))
+        return diagnostics
+
+    def render_value(self, value: TclInputValue) -> str:
+        """Render one Tcl input value as Tcl text."""
+        value = _coerce_value(value)
+        if isinstance(value, Scalar):
+            return _quote_tcl_word(str(value.value))
+        if isinstance(value, PathValue):
+            return _quote_tcl_word(value.value)
+        if isinstance(value, ListValue):
+            return "[list " + " ".join(self.render_value(item) for item in value.values) + "]"
+        if isinstance(value, VarRef):
+            if not value.name:
+                raise BuildError("empty Tcl variable reference")
+            return f"${value.name}"
+        if isinstance(value, Expr):
+            return f"[expr {{{value.expression}}}]"
+        if isinstance(value, CommandSubstitution):
+            words = [value.command, *(self.render_value(arg) for arg in value.args)]
+            return "[" + " ".join(words) + "]"
+        if isinstance(value, Raw):
+            return value.text
+        raise BuildError(f"unsupported Tcl value: {value!r}")
+
+    def _render_node(self, node: TclNode, *, level: int) -> str:
+        prefix = self.indent * level
+        if isinstance(node, Comment):
+            return "".join(
+                f"{prefix}# {_escape_comment_line(line)}\n"
+                for line in _comment_lines(node.text)
+            )
+        if isinstance(node, BlankLine):
+            return "\n"
+        if isinstance(node, Set):
+            return f"{prefix}set {node.name} {self.render_value(node.value)}\n"
+        if isinstance(node, Command):
+            args = " ".join(self.render_value(arg) for arg in node.args)
+            line = f"{node.name} {args}" if args else node.name
+            return f"{prefix}{line}\n"
+        if isinstance(node, If):
+            body = "".join(self._render_node(child, level=level + 1) for child in node.body)
+            return f"{prefix}if {{{node.condition.text}}} {{\n{body}{prefix}}}\n"
+        if isinstance(node, RawLine):
+            return f"{prefix}{node.text}\n"
+        raise BuildError(f"unsupported Tcl node: {node!r}")
+
+    def _validate_node(self, node: TclNode) -> list[Diagnostic]:
+        diagnostics: list[Diagnostic] = []
+        if isinstance(node, Set):
+            if not node.name:
+                diagnostics.append(
+                    Diagnostic("empty-variable-name", "variable name is required", node.origin)
+                )
+            diagnostics.extend(
+                _validate_value(node.value, origin=node.origin, scalar_api=node.scalar_api)
+            )
+        elif isinstance(node, Command):
+            if not node.name:
+                diagnostics.append(
+                    Diagnostic("empty-command-name", "command name is required", node.origin)
+                )
+            for arg in node.args:
+                diagnostics.extend(_validate_value(arg, origin=node.origin, scalar_api=False))
+        elif isinstance(node, If):
+            if not node.condition.text:
+                diagnostics.append(
+                    Diagnostic("empty-condition", "condition is required", node.origin)
+                )
+            for item in node.condition.diagnostics:
+                diagnostics.append(_diagnostic_with_origin(item, node.origin))
+            for child in node.body:
+                diagnostics.extend(self._validate_node(child))
+        elif isinstance(node, RawLine):
+            diagnostics.append(
+                Diagnostic("unsafe-raw", "raw Tcl line requires explicit opt-in", node.origin)
+            )
+        elif isinstance(node, (Comment, BlankLine)):
+            pass
+        else:
+            diagnostics.append(
+                Diagnostic("unsupported-node", f"unsupported Tcl node {type(node).__name__}")
+            )
+        return diagnostics
+
+
+def _coerce_value(value: TclInputValue) -> TclValue:
+    if isinstance(value, (Scalar, PathValue, ListValue, VarRef, Expr, CommandSubstitution, Raw)):
+        return value
+    return Scalar(value)
+
+
+def _diagnostic_with_origin(diagnostic: Diagnostic, origin: str | None) -> Diagnostic:
+    if diagnostic.origin or origin is None:
+        return diagnostic
+    return Diagnostic(diagnostic.code, diagnostic.message, origin)
+
+
+def _validate_value(
+    value: TclInputValue,
+    *,
+    origin: str | None,
+    scalar_api: bool,
+) -> list[Diagnostic]:
+    value = _coerce_value(value)
+    diagnostics: list[Diagnostic] = []
+    if isinstance(value, PathValue):
+        if value.value == "":
+            diagnostics.append(Diagnostic("empty-path", "path value is required", origin))
+        elif _needs_quoting(value.value):
+            diagnostics.append(Diagnostic("quoted-path", "path requires Tcl quoting", origin))
+    elif isinstance(value, ListValue):
+        if scalar_api:
+            diagnostics.append(
+                Diagnostic("list-through-scalar-api", "use set_list for Tcl list values", origin)
+            )
+        for item in value.values:
+            diagnostics.extend(_validate_value(item, origin=origin, scalar_api=False))
+    elif isinstance(value, VarRef) and not value.name:
+        diagnostics.append(
+            Diagnostic("empty-variable-name", "variable reference name is required", origin)
+        )
+    elif isinstance(value, CommandSubstitution):
+        if not value.command:
+            diagnostics.append(Diagnostic("empty-command-name", "command name is required", origin))
+        for arg in value.args:
+            diagnostics.extend(_validate_value(arg, origin=origin, scalar_api=False))
+    elif isinstance(value, Raw):
+        diagnostics.append(
+            Diagnostic("unsafe-raw", "raw Tcl value requires explicit opt-in", origin)
+        )
+    return diagnostics
+
+
+def _quote_tcl_word(text: str) -> str:
+    if text == "":
+        return "{}"
+    if not _needs_quoting(text):
+        return text
+    if "{" not in text and "}" not in text and "\n" not in text and "\r" not in text:
+        return "{" + text + "}"
+    return "".join(_escape_unbraced_char(char) for char in text)
+
+
+def _needs_quoting(text: str) -> bool:
+    return text == "" or any(char.isspace() or char in "{}[]$;\\\"" for char in text)
+
+
+def _escape_unbraced_char(char: str) -> str:
+    replacements = {
+        " ": "\\ ",
+        "\t": "\\t",
+        "\n": "\\n",
+        "\r": "\\r",
+        "\\": "\\\\",
+        "{": "\\{",
+        "}": "\\}",
+        "[": "\\[",
+        "]": "\\]",
+        "$": "\\$",
+        ";": "\\;",
+        '"': '\\"',
+    }
+    return replacements.get(char, char)
+
+
+def _comment_lines(text: str) -> list[str]:
+    return text.splitlines() or [""]
+
+
+def _escape_comment_line(line: str) -> str:
+    return line.replace("\\", "\\\\").replace("{", "\\{").replace("}", "\\}")

rosettakit-0.2.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: rosettakit
+Version: 0.2.0
+Summary: Typed Python builders for EDA scripts and command files
+Author: Emin
+Author-email: Emin <me@emin.chat>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/Emin017/RosettaKit
+Project-URL: Repository, https://github.com/Emin017/RosettaKit
+Project-URL: Issues, https://github.com/Emin017/RosettaKit/issues
+Description-Content-Type: text/markdown
+
+# RosettaKit
+
+RosettaKit is a small Python library for building typed EDA script documents and
+rendering them into tool-facing text such as Tcl fragments and command files.
+
+## API Stability
+
+RosettaKit 0.2.0 treats the public node, value, document, and builder APIs as
+stable:
+
+- `rosettakit.tcl`: `Script`, `TclBuilder`, `Scalar`, `PathValue`,
+  `ListValue`, `VarRef`, `Expr`, `CommandSubstitution`, `Raw`, `Condition`,
+  `Comment`, `BlankLine`, `Set`, `Command`, `If`, `RawLine`, and helper
+  functions such as `word`, `path`, `list_value`, `var`, `expr`, `call`, `raw`,
+  and `file_isdirectory`.
+- `rosettakit.cmdfile`: `CommandFile`, `CommandFileBuilder`, `ValueType`,
+  `ValueQuoting`, `CommandFileDialect`, `TCL_WORD_DIALECT`, `PLAIN_DIALECT`,
+  `Comment`, `BlankLine`, `Flag`, `Option`, and `RawLine`.
+- `rosettakit.diagnostics.Diagnostic` and the exception hierarchy in
+  `rosettakit.errors`.
+
+Generated text is part of the compatibility surface. Patch releases should not
+change quoting, indentation, line ordering, or default raw-content policy unless
+the current output is unsafe or invalid.
+
+RosettaKit only builds script text. It does not parse Tcl, execute EDA tools,
+manage subprocesses, or model a host workflow.
+
+## Tcl API
+
+```python
+from rosettakit import tcl
+
+script = tcl.Script()
+script.comment("Auto-generated by RosettaKit")
+script.set("top_design", tcl.word("gcd_core"))
+script.set("clk_freq_mhz", 500)
+script.set_path("final_netlist_file", "build out/gcd final.v")
+script.set_list("lib_list", ["libs/fast corner.lib", "libs/slow.lib"])
+script.set_expr("clk_period_ps", "1000000.0 / $clk_freq_mhz")
+script.set_path("tmp_dir", "build out/tmp")
+script.file_mkdir(tcl.var("tmp_dir"))
+
+text = script.build()
+```
+
+Use `script.validate()` to inspect diagnostics before building. Raw Tcl is an
+explicit escape hatch through `tcl.raw(...)` or `script.raw_line(...)`; builds
+fail on raw content unless `allow_unsafe_raw=True` is passed.
+
+## Command File API
+
+```python
+from rosettakit import cmdfile
+
+cmd = cmdfile.CommandFile(prefix="-")
+cmd.flag("useOpenSTA")
+cmd.option("top", "gcd_core")
+cmd.option("def", "build out/input.def", value_type=cmdfile.ValueType.PATH)
+cmd.options("lef", ["tech/sky130.lef", "macro lef/sram.lef"], value_type=cmdfile.ValueType.PATH)
+
+text = cmd.build()
+```
+
+Command files preserve insertion order, support flags, single options,
+repeated options, optional omission of empty values, and path-aware quoting.
+`PLAIN_DIALECT` emits unquoted whitespace-delimited option values and rejects
+values that cannot be represented safely in that form.
+
+## Examples
+
+The first-party examples use only RosettaKit and Python standard-library
+modules:
+
+```bash
+uv run python examples/yosys_global_var.py
+uv run python examples/sizer_cmd_file.py
+uv run python examples/sizer_env_file.py
+```
+
+They write generated output under ignored paths:
+
+```text
+examples/out/yosys/global_var.tcl
+examples/out/sizer/design.cmd_file
+examples/out/sizer/design.env_file
+```
+
+To verify the generated Tcl with a local Tcl shell:
+
+```bash
+uv run python examples/yosys_global_var.py
+tclsh examples/out/yosys/global_var.tcl
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check
+```

rosettakit-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+rosettakit/__init__.py,sha256=GLZerkEC4XoYM-TwcRwOCCsz5S6Q-zL3fwgb5ulDObE,100
+rosettakit/cmdfile.py,sha256=UIOaS_WE_QWcDZMizAZZOdtB25AJiIbMqOSUQS_odHQ,12570
+rosettakit/diagnostics.py,sha256=86Uy9Th5sQzEc4KenOElfz0t8imiC2hUqxgmDhAH8CY,175
+rosettakit/errors.py,sha256=iedI1i28nGBKvCEgdc5LNCLTu71Bpdj1IwmfU6uxrzI,1041
+rosettakit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosettakit/tcl.py,sha256=Khl2MmSn-V5B1VrHCmeNHE_Vu3_IfzR6JfyAnIVD6ZY,17030
+rosettakit-0.2.0.dist-info/licenses/LICENSE,sha256=8KuYVmQGvdTeu0tP1UW3POnWymWvHHUQJM2cdvpc01c,11334
+rosettakit-0.2.0.dist-info/WHEEL,sha256=wXwAVsgVaOZ_pwDFqQm5Rd6PID-Fc74nkLc8X8gHiDo,81
+rosettakit-0.2.0.dist-info/METADATA,sha256=zXyjJxtSlgXt9CcCKHSgIh6grXFyQlJFs4p1TFvsnec,3941
+rosettakit-0.2.0.dist-info/RECORD,,

rosettakit-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.19
+Root-Is-Purelib: true
+Tag: py3-none-any

rosettakit-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Emin
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.