base

Classes:

• Builder –
• BuilderVisitor –
• CommandError –
• CommandResult –

Functions:

• run_command –

Builder

Builder()

Bases: ABC

Methods:

• activate_runtime_feature –
• build –
• module –
• run –
• translate –

Source code in src/irx/builder/base.py

def __init__(self) -> None:
    """
    title: Initialize Builder object.
    """
    self.translator = BuilderVisitor()
    self.tmp_path = ""
    self.output_file = ""
    self.sh_args: dict[str, Any] = dict(
        _in=sys.stdin,
        _out=sys.stdout,
        _err=sys.stderr,
        _env=os.environ,
        # _new_session=True,
    )
    self.runtime_feature_names = set()

activate_runtime_feature

activate_runtime_feature(feature_name: str) -> None

Source code in src/irx/builder/base.py

def activate_runtime_feature(self, feature_name: str) -> None:
    """
    title: Activate a native runtime feature for this compilation unit.
    parameters:
      feature_name:
        type: str
    """
    self.runtime_feature_names.add(feature_name)

build abstractmethod

build(expr: AST, output_file: str) -> None

Source code in src/irx/builder/base.py

@abstractmethod
def build(
    self,
    expr: astx.AST,
    output_file: str,  # noqa: F841, RUF100
) -> None:
    """
    title: Transpile ASTx to LLVM-IR and build an executable file.
    parameters:
      expr:
        type: astx.AST
      output_file:
        type: str
    """
    ...

module

module() -> Module

Source code in src/irx/builder/base.py

def module(self) -> astx.Module:
    """
    title: Create a new ASTx Module.
    returns:
      type: astx.Module
    """
    return astx.Module()

run

run(
    *,
    capture_stderr: bool = True,
    raise_on_error: bool = True,
    debug: bool = False,
) -> CommandResult

Source code in src/irx/builder/base.py

def run(
    self,
    *,
    capture_stderr: bool = True,
    raise_on_error: bool = True,
    debug: bool = False,
) -> CommandResult:
    """
    title: Run the generated executable.
    parameters:
      capture_stderr:
        type: bool
        default: true
      raise_on_error:
        type: bool
        default: true
      debug:
        type: bool
        default: false
    returns:
      type: CommandResult
    """
    return run_command(
        [self.output_file],
        capture_stderr=capture_stderr,
        raise_on_error=raise_on_error,
        debug=debug,
    )

translate

translate(expr: AST) -> str

Source code in src/irx/builder/base.py

def translate(self, expr: astx.AST) -> str:
    """
    title: Transpile ASTx to LLVM-IR.
    parameters:
      expr:
        type: astx.AST
    returns:
      type: str
    """
    return self.translator.translate(expr)

BuilderVisitor

Bases: BaseVisitor

Methods:

• translate –
• visit –
• visit_child –

translate

translate(expr: AST) -> str

self.visit(expr) return str(self.result)

Source code in src/irx/builder/base.py

def translate(self, expr: astx.AST) -> str:
    """
    title: Translate an ASTx expression to string.
    parameters:
      expr:
        type: astx.AST
    returns:
      type: str
    examples: |-
      self.visit(expr)
      return str(self.result)
    """
    raise Exception("Not implemented yet.")

visit

visit(node: AST) -> None

Source code in src/irx/builder/base.py

@dispatch
def visit(self, node: astx.AST) -> None:
    """
    title: Visit AST nodes.
    parameters:
      node:
        type: astx.AST
    """
    super().visit(node)

visit_child

visit_child(node: AST) -> None

Source code in src/irx/builder/base.py

def visit_child(self, node: astx.AST) -> None:
    """
    title: Forward a child AST node through the public visit dispatcher.
    parameters:
      node:
        type: astx.AST
    """
    self.visit(node)

CommandError

CommandError(result: CommandResult)

Bases: RuntimeError

Source code in src/irx/builder/base.py

def __init__(self, result: CommandResult) -> None:
    """
    title: Initialize CommandError.
    parameters:
      result:
        type: CommandResult
    """
    self.result: CommandResult = result
    super().__init__(
        f"Command {list(result.command)!r} failed "
        f"(exit {result.returncode}):\n{result.stderr.strip()}"
    )

CommandResult dataclass

CommandResult(
    stdout: str,
    stderr: str,
    returncode: int,
    command: Sequence[str],
)

Attributes:

• success (bool) –

success property

success: bool

run_command

run_command(
    command: Sequence[str],
    *,
    capture_stderr: bool = True,
    raise_on_error: bool = True,
    debug: bool = False,
) -> CommandResult

Source code in src/irx/builder/base.py

@typechecked
def run_command(
    command: Sequence[str],
    *,
    capture_stderr: bool = True,
    raise_on_error: bool = True,
    debug: bool = False,
) -> CommandResult:
    """
    title: Run a shell command and return a structured CommandResult.
    parameters:
      command:
        type: Sequence[str]
      capture_stderr:
        type: bool
        default: true
      raise_on_error:
        type: bool
        default: true
      debug:
        type: bool
        default: false
    returns:
      type: CommandResult
    raises:
      CommandError: When the command exits non-zero and raise_on_error=True.
    """
    if debug:
        logger.debug("run_command: %s", list(command))

    stderr_arg = subprocess.PIPE if capture_stderr else None

    try:
        proc = subprocess.run(
            command,
            check=False,
            stdout=subprocess.PIPE,
            stderr=stderr_arg,
            text=True,
        )
    except FileNotFoundError as exc:
        result = CommandResult(
            stdout="",
            stderr=str(exc),
            returncode=127,
            command=command,
        )
        if raise_on_error:
            raise CommandError(result) from exc
        return result

    result = CommandResult(
        stdout=proc.stdout or "",
        stderr=proc.stderr or "",
        returncode=proc.returncode,
        command=command,
    )

    if debug:
        logger.debug(
            "exit=%d stdout=%r stderr=%r",
            result.returncode,
            result.stdout[:200],
            result.stderr[:200],
        )

    if raise_on_error and not result.success:
        raise CommandError(result)

    return result