bxengine 0.1.0__tar.gz

bxengine-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: bxengine
+Version: 0.1.0
+Summary: B++ runtime engine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Interpreters
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# bxengine
+
+`bxengine` is a Python implementation of the B++ runtime engine.
+
+## Install
+
+```bash
+pip install bxengine
+```
+
+## CLI
+
+Run a file:
+
+```bash
+bxengine path/to/program.bx
+```
+
+Run inline code:
+
+```bash
+bxengine -e "[CONCAT \"hello\" \" world\"]"
+```
+
+## Development
+
+```bash
+uv sync --dev
+pytest
+```

bxengine-0.1.0/README.md

@@ -0,0 +1,30 @@
+# bxengine
+
+`bxengine` is a Python implementation of the B++ runtime engine.
+
+## Install
+
+```bash
+pip install bxengine
+```
+
+## CLI
+
+Run a file:
+
+```bash
+bxengine path/to/program.bx
+```
+
+Run inline code:
+
+```bash
+bxengine -e "[CONCAT \"hello\" \" world\"]"
+```
+
+## Development
+
+```bash
+uv sync --dev
+pytest
+```

bxengine-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=69.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bxengine"
+dynamic = ["version"]
+description = "B++ runtime engine"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Interpreters",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+bxengine = "bxengine.module:_module_main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["bxengine*"]
+
+[tool.setuptools.dynamic]
+version = {attr = "bxengine.__version__"}
+
+[dependency-groups]
+dev = [
+    "build>=1.2.2",
+    "pytest>=9.0.3",
+    "twine>=6.1.0",
+]

bxengine-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bxengine-0.1.0/src/bxengine/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

bxengine-0.1.0/src/bxengine/__init__.py

@@ -0,0 +1,3 @@
+from .__about__ import __version__
+
+__all__ = ["__version__"]

bxengine-0.1.0/src/bxengine/__main__.py

@@ -0,0 +1,4 @@
+from bxengine.module import _module_main
+
+if __name__ == "__main__":
+    _module_main()

bxengine-0.1.0/src/bxengine/constants.py

@@ -0,0 +1,2 @@
+
+ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"

bxengine-0.1.0/src/bxengine/exceptions.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from bxengine.spans import SpanData
+
+
+class BxeRuntimeException(Exception):
+    def __init__(self, message: str = "", span: SpanData | None = None):
+        super().__init__(message)
+        self.span = span
+
+class BxeSyntaxException(Exception):
+    pass
+
+class BxeUnclosedStringException(BxeSyntaxException):
+    def __init__(self, position: int = -1):
+        super().__init__("Unclosed string")
+        self.position = position
+
+class BxeRuntimeSyntaxException(BxeRuntimeException):
+    pass

bxengine-0.1.0/src/bxengine/module.py

@@ -0,0 +1,72 @@
+import argparse
+import sys
+
+from bxengine.runtime.extensions.BxeExtension import GlobalVariableBppExtension
+from bxengine.runtime.extensions.discord_stub import DiscordStubExtension
+from bxengine.tokenizer.tokenize import Tokenizer, TokenizationResult
+from bxengine.parsing.parser import Parser, ParsingResult
+from bxengine.runtime.executor import Executor, ExecutorResult
+from bxengine.runtime.extensions.builtin import BuiltinExtension
+
+
+DEFAULT_TEST = """
+[GLOBAL DEFINE descentNumber 100]
+[GLOBAL DEFINE descentAttempts 0]
+[GLOBAL DEFINE descentHighscore 15]
+
+[DEFINE number [GLOBAL VAR descentNumber]]
+[DEFINE attempts [GLOBAL VAR descentAttempts]]
+[DEFINE nextNumber [RANDINT 0 [MATH [VAR number] + 1]]]
+[IF [COMPARE [VAR nextNumber] != 0] [CONCAT "The number has gone from **" [VAR number] "** to **" [VAR nextNumber] "**. The current number of tries in this run is **" [MATH [VAR attempts] + 1] "**!
+" [IF [COMPARE [GLOBAL VAR descentHighscore] < [MATH [VAR attempts] + 1]] [CONCAT "You've successfully beaten the highscore of **" [GLOBAL VAR descentHighscore] "**, but you're still going! Good luck!"] [CONCAT "The highscore to beat is **" [GLOBAL VAR descentHighscore] "**."]]] [CONCAT "Uh oh, looks like this run has finally come to an end! You had **" [MATH [VAR attempts] + 1] "** attempts.
+" [IF [COMPARE [GLOBAL VAR descentHighscore] < [MATH [VAR atoh
+yetempts] + 1]] [CONCAT "But I'm pleased to say you beat the highscore of **" [GLOBAL VAR descentHighscore] "** with your new score of **" [MATH [VAR attempts] + 1] "**! Well done!"] [CONCAT "Unfortunately, you failed to beat the highscore of **" [GLOBAL VAR descentHighscore] "**. I'm sure next attempt will be more promising, though."]]]]
+[IF [COMPARE [VAR nextNumber] != 0] [CONCAT [GLOBAL DEFINE descentAttempts [MATH [VAR attempts] + 1]] [GLOBAL DEFINE descentNumber [VAR nextNumber]]] [CONCAT [IF [COMPARE [GLOBAL VAR descentHighscore] < [MATH [VAR attempts] + 1]] [GLOBAL DEFINE descentHighscore [MATH [VAR attempts] + 1]]] [GLOBAL DEFINE descentAttempts 0] [GLOBAL DEFINE descentNumber 100]]
+"""
+
+
+def run_code(code: str, program_args: list[str] | None = None) -> None:
+    tokenizer_res = Tokenizer.tokenize(code)
+    if isinstance(tokenizer_res, TokenizationResult.Error):
+        print(tokenizer_res.message, "\n\n", tokenizer_res.range.debug_info(), sep="")
+        return
+
+    parser_res = Parser.parse(code, tokenizer_res.tokens)
+    if isinstance(parser_res, ParsingResult.Error):
+        print(parser_res.message, "\n\n", parser_res.range.debug_info(), sep="")
+        return
+
+    executor = Executor(
+        extensions=[BuiltinExtension()],
+        stateful_extensions=[GlobalVariableBppExtension, DiscordStubExtension],
+        program_args=program_args or [],
+    )
+    result = executor.execute(parser_res.nodes)
+
+    if isinstance(result, ExecutorResult.Error):
+        exception = result.exception
+        print(type(exception).__name__ + ":", exception, file=sys.stderr)
+        span = getattr(exception, "span", None)
+        if span is not None:
+            print("", file=sys.stderr)
+            print(span.debug_info(), file=sys.stderr)
+        sys.exit(1)
+    else:
+        print(result.output.strip(), end="\n")
+
+
+def _module_main():
+    parser = argparse.ArgumentParser(prog="bxengine", description="B++ runtime engine")
+    parser.add_argument("file", nargs="?", help="Path to a .bx script file")
+    parser.add_argument("-e", "--eval", metavar="CODE", help="Execute a string of B++ code")
+    parser.add_argument("args", nargs="*", help="Arguments passed to the script (accessible via ARGS)")
+
+    parsed = parser.parse_args()
+
+    if parsed.eval:
+        run_code(parsed.eval, parsed.args)
+    elif parsed.file:
+        with open(parsed.file) as f:
+            run_code(f.read(), parsed.args)
+    else:
+        run_code(DEFAULT_TEST, parsed.args)

bxengine-0.1.0/src/bxengine/parsing/nodes.py

@@ -0,0 +1,40 @@
+from dataclasses import dataclass
+from typing import List
+from bxengine.spans import SpanData
+
+class Node:
+    pass
+
+class Nodes:
+    @dataclass(frozen=True)
+    class Error(Node):
+        message: str
+        range: SpanData
+
+    """
+    This is only used internally, package users do not need to handle _Complete.
+    """
+    @dataclass(frozen=True)
+    class _Complete(Node):
+        range: SpanData
+
+    @dataclass(frozen=True)
+    class OuterText(Node):
+        value: str
+        range: SpanData
+
+    @dataclass(frozen=True)
+    class Function(Node):
+        name: str
+        arguments: List[Node]
+        range: SpanData
+
+    @dataclass(frozen=True)
+    class Number(Node):
+        value: str
+        range: SpanData
+
+    @dataclass(frozen=True)
+    class StringNode(Node):
+        value: str
+        range: SpanData

bxengine-0.1.0/src/bxengine/parsing/parser.py

@@ -0,0 +1,204 @@
+from bxengine.parsing.nodes import Node, Nodes
+from typing import List, Tuple, Sequence
+from bxengine.tokenizer.tokens import Token, Tokens
+from bxengine.spans import SpanData
+from dataclasses import dataclass
+import functools
+
+
+class ParsingResult:
+    @dataclass(frozen=True)
+    class Error:
+        message: str
+        range: SpanData
+
+    @dataclass(frozen=True)
+    class Success:
+        nodes: List[Node]
+
+        def pretty(self) -> str:
+            string = f"{len(self.nodes)} nodes:"
+            for node in self.nodes:
+                string += "\n"
+                string += str(node)
+
+            return string
+
+
+class Parser:
+    _identity_cache: dict[int, tuple[str, Sequence[Token], ParsingResult.Success | ParsingResult.Error]] = {}
+    _identity_cache_limit: int = 512
+
+    def __init__(self):
+        self.nesting_level: int = 0
+        self.nesting_token_indexes: List[int] = []
+        self.contents: str = ""
+        self.token_list: Sequence[Token] = ()
+        self.is_function_declaration: bool = False
+        self.index: int = 0
+
+    @staticmethod
+    def parse(contents: str, token_list: Sequence[Token]) -> ParsingResult.Success | ParsingResult.Error:
+        # Fast path for repeated runs with the same token list object (common when
+        # tokenization cache hits across multiple executions in one process).
+        cache_key = id(token_list)
+        cached = Parser._identity_cache.get(cache_key)
+        if cached is not None:
+            cached_contents, cached_tokens, cached_result = cached
+            if cached_contents == contents and cached_tokens is token_list:
+                return cached_result
+
+        result = Parser._parse_cache(contents, tuple(token_list))
+
+        if len(Parser._identity_cache) >= Parser._identity_cache_limit:
+            Parser._identity_cache.clear()
+        Parser._identity_cache[cache_key] = (contents, token_list, result)
+        return result
+
+    @staticmethod
+    @functools.lru_cache(maxsize=128, typed=False)
+    def _parse_cache(contents: str, token_list: Tuple[Token]) -> ParsingResult.Success | ParsingResult.Error:
+        parser = Parser()
+        parser.contents = contents
+        parser.token_list = token_list
+        parser.nesting_level = 0
+        parser.nesting_token_indexes = []
+        parser.index = 0
+        parser.is_function_declaration = False
+
+        return parser._parse_loop()
+
+    def _parse_loop(self) -> ParsingResult.Success | ParsingResult.Error:
+        node_list = []
+        while True:
+            node = self._parse_once()
+
+            if isinstance(node, Nodes.Error):
+                return ParsingResult.Error(node.message, node.range)
+            elif isinstance(node, Nodes._Complete):
+                return ParsingResult.Success(node_list)
+
+            node_list.append(node)
+
+    def _parse_once(self) -> Node:
+        return self._parse_inner()
+
+    def _parse_inner(self) -> Node:
+        token = self.token_list[self.index]
+
+        if isinstance(token, Tokens.EndOfFile):
+            if self.nesting_level > 0:
+                bracket_index = self.nesting_token_indexes[-1]
+                return Nodes.Error("Unclosed bracket.", self.token_list[bracket_index].range)
+            else:
+                return Nodes._Complete(token.range)
+
+        if isinstance(token, Tokens.Error):
+            self.index += 1
+            return Nodes.Error(token.message, token.range)
+
+        if self.nesting_level == 0:
+            match token:
+                case Tokens.OuterString():
+                    self.index += 1
+                    return Nodes.OuterText(token.value, token.range)
+                case Tokens.OpenBracket():
+                    return self._parse_function()
+                case _:
+                    self.index += 1
+                    text = self.contents[token.range.cursor_start:token.range.cursor_end]
+                    return Nodes.Error(
+                        f"Unexpected token '{text}' at top level. Only text and function calls are allowed.",
+                        token.range
+                    )
+        else:
+            self.index += 1
+            return Nodes.Error("Parser bug: `_parse_inner` called while (somehow??) nested. Please report this!",
+                               token.range)
+
+    def _parse_function(self) -> Node:
+        open_bracket = self.token_list[self.index]  # this is always an OpenBracket
+        self.index += 1  # consume
+
+        self.nesting_level += 1
+        self.nesting_token_indexes.append(self.index - 1)
+
+        if self.index >= len(self.token_list):
+            self.nesting_level -= 1
+            self.nesting_token_indexes.pop()
+            # Equivalent to empty brackets `[]` due to auto-close.
+            return Nodes.Error("Function call cannot be empty `[]`.", self.create_span(open_bracket, open_bracket))
+
+        name_token = self.token_list[self.index]
+
+        # BPPCOMPAT: Close on EndOfFile just like a CloseBracket
+        if isinstance(name_token, (Tokens.CloseBracket, Tokens.EndOfFile)):
+            if isinstance(name_token, Tokens.CloseBracket):
+                self.index += 1
+            self.nesting_level -= 1
+            self.nesting_token_indexes.pop()
+            return Nodes.Error("Function call cannot be empty `[]`.", self.create_span(open_bracket, name_token))
+
+        if not isinstance(name_token, Tokens.UnquotedString):
+            self.nesting_level -= 1
+            self.nesting_token_indexes.pop()
+            return Nodes.Error("Function name must be an unquoted string.", name_token.range)
+
+        self.index += 1  # consume
+
+        function_name = name_token.value
+        arguments = []
+
+        while True:
+            if self.index >= len(self.token_list):
+                self.nesting_level -= 1
+                self.nesting_token_indexes.pop()
+                last_token = self.token_list[-1] if self.token_list else open_bracket
+                return Nodes.Function(function_name, arguments, self.create_span(open_bracket, last_token))
+
+            current = self.token_list[self.index]
+
+            # BPPCOMPAT: Close on EndOfFile just like a CloseBracket
+            if isinstance(current, (Tokens.CloseBracket, Tokens.EndOfFile)):
+                if isinstance(current, Tokens.CloseBracket):
+                    self.index += 1
+                self.nesting_level -= 1
+                self.nesting_token_indexes.pop()
+                return Nodes.Function(function_name, arguments, self.create_span(open_bracket, current))
+
+            argument = self._parse_expression()
+            if isinstance(argument, Nodes.Error):
+                return argument
+
+            arguments.append(argument)
+
+    def _parse_expression(self) -> Node:
+        token = self.token_list[self.index]
+
+        if isinstance(token, Tokens.Error):
+            self.index += 1
+            return Nodes.Error(token.message, token.range)
+
+        match token:
+            case Tokens.OpenBracket():
+                return self._parse_function()
+            case Tokens.Number():
+                self.index += 1
+                return Nodes.Number(token.value, token.range)
+            case Tokens.QuotedString():
+                self.index += 1
+                return Nodes.StringNode(token.value, token.range)
+            case Tokens.UnquotedString():
+                self.index += 1
+                return Nodes.StringNode(token.value, token.range)
+            case Tokens.EndOfFile():
+                bracket_index = self.nesting_token_indexes[-1]
+                return Nodes.Error("Parser bug: `_parse_expression` called and hit end of file (should be impossible...!)", self.token_list[bracket_index].range)
+            case _:
+                self.index += 1
+                return Nodes.Error("Unexpected token while parsing arguments.", token.range)
+
+    def create_span(self, start: Token, end: Token) -> SpanData:
+        start_int = start.range.cursor_start
+        end_int = end.range.cursor_end
+        return SpanData(start_int, end_int, self.contents)

bxengine-0.1.0/src/bxengine/runtime/__init__.py

@@ -0,0 +1,4 @@
+from bxengine.runtime.context import RuntimeContext
+from bxengine.runtime.executor import Executor, ExecutorResult, FunctionEntry
+
+__all__ = ["RuntimeContext", "Executor", "ExecutorResult", "FunctionEntry"]

bxengine-0.1.0/src/bxengine/runtime/context.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bxengine.runtime.executor import Executor, FunctionEntry
+
+
+@dataclass
+class RuntimeContext:
+    local_variables: dict[str, Any] = field(default_factory=dict)
+    program_args: list[Any] = field(default_factory=list)
+    executor: Executor | None = None
+    functions: dict[str, FunctionEntry] = field(default_factory=dict)