spacelanguage 0.1.0__tar.gz

spacelanguage-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e . pytest
+      - run: python -m pytest -q

spacelanguage-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+build/
+dist/
+*.egg-info/

spacelanguage-0.1.0/CMakeLists.txt

@@ -0,0 +1,13 @@
+cmake_minimum_required(VERSION 3.18)
+project(spacelang_cpp LANGUAGES CXX)
+
+find_package(Python REQUIRED COMPONENTS Interpreter Development.Module)
+find_package(pybind11 CONFIG REQUIRED)
+
+pybind11_add_module(_spacelang_cpp MODULE
+    csrc/binding.cpp
+    csrc/vm.cpp
+)
+target_compile_features(_spacelang_cpp PRIVATE cxx_std_17)
+target_include_directories(_spacelang_cpp PRIVATE csrc)
+install(TARGETS _spacelang_cpp LIBRARY DESTINATION spacelang)

spacelanguage-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.2
+Name: spacelanguage
+Version: 0.1.0
+Summary: SpaceLang core package
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SpaceLang
+
+SpaceLang is an experimental stack-based language toolkit. It currently
+contains a Python reference VM, an experimental C++ VM, a small Python-subset
+frontend, and tools for assembling, disassembling, and encoding SpaceLang
+programs.
+
+> **Status:** Early development. The frontend and VM implement a subset of
+> Python and the project is not yet a drop-in Python runtime. See the source and
+> tests for the behavior currently supported.
+
+## Requirements
+
+- Python 3.10 or newer
+- A C++17 compiler and CMake 3.18 or newer to build the native extension
+
+## Install
+
+Clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/DwwLSM/spacelang.git
+cd spacelang
+python -m pip install -e .
+```
+
+For development, install pytest as well:
+
+```bash
+python -m pip install pytest
+python -m pytest
+```
+
+## Run Python-subset source
+
+Compile supported Python syntax to a SpaceLang program, then execute it with
+the reference VM:
+
+```python
+from spacelang.pyfront import compile_py
+from spacelang.vm_py import VM
+
+source = """
+def add(a, b):
+    return a + b
+
+i = 0
+while i < 3:
+    print(add(i, 2))
+    i = i + 1
+"""
+
+program = compile_py(source)
+VM(program).run()
+```
+
+Output:
+
+```text
+2
+3
+4
+```
+
+The current frontend handles basic integer, boolean, and string constants,
+arithmetic, comparisons, boolean expressions, calls, assignments, supported
+imports, `if`/`else`, `while`, simple positional functions, and `for` loops
+over `range(...)`. Sequence indexing is supported for indexable values.
+
+This is still a Python subset, not full Python; features such as classes,
+exceptions in source code, generators, nested or filtered comprehensions,
+keyword arguments to user functions, and general iterator protocols are not implemented.
+Unsupported syntax raises an error rather than being silently compiled.
+
+## Create a self-copying program
+
+For Python files, `quine` writes a new file with a small hook that copies that
+generated file to a `.copy.py` sibling when run. The input file is left
+unchanged:
+
+```python
+from spacelang.quine import quine
+
+quine("example.py", "example_quine.py")
+```
+
+Then run `python example_quine.py`. The CLI equivalent is:
+
+```bash
+python -m spacelang.quine example.py example_quine.py
+```
+
+The CLI also supports `--in-place --yes`; it creates a `.bak` backup before
+replacing the source. The Python API itself rejects in-place operation.
+SpaceLang `.sp`/`.spz` quines produce a companion `.names.json` file because
+the instruction stream stores name IDs, not their textual names.
+
+## Command-line tools
+
+The command-line interface supports Python compilation, assembly,
+disassembly, execution with the reference VM, and `.sp`/`.spz` compression:
+
+```bash
+python -m spacelang.main compile-py example.py example.sp
+python -m spacelang.main run example.sp
+python -m spacelang.main run example.sp --engine cpp
+python -m spacelang.main disasm example.sp
+python -m spacelang.main pack example.sp
+python -m spacelang.main run example.spz
+```
+
+Compilation enables the safe peephole optimizations and integer constant pool
+by default. Pass `--no-optimize` to `compile-py` to preserve the frontend IR,
+or `--compress-source` to factorize large integer constants before encoding.
+The C++ engine is experimental and is not the default. GCC and Clang builds use
+computed-goto instruction dispatch; other compilers use a portable switch
+dispatcher. Use the Python engine as the reference for behavior that has not
+yet been verified for native parity.
+
+To compare both engines on the same recursive workload after installation:
+
+```bash
+python -m benchmarks.benchmark_vm --n 25 --repeat 3
+```
+
+The benchmark checks that both engines return the same result and reports the
+median runtime and speedup. Timings depend on the host and are not a performance
+guarantee.
+
+## Assemble and run instructions
+
+The assembler accepts one mnemonic instruction per line. For example:
+
+```python
+from spacelang.asm import assemble
+from spacelang.vm_py import VM
+
+program = assemble("""
+PUSH_INT 2
+PUSH_INT 3
+OP 1
+HALT
+""")
+
+print(VM(program).run())
+```
+
+`OP 1` adds the two values on top of the stack. This example prints `5`.
+
+## Inspect and encode programs
+
+```python
+from spacelang.asm import assemble
+from spacelang.disasm import disassemble
+from spacelang.encoder import encode
+from spacelang.lexer import tokenize
+from spacelang.parser import parse
+
+program = assemble("PUSH_INT 2\nPUSH_INT 3\nOP 1\nHALT\n")
+
+print(disassemble(program))   # Human-readable instructions
+encoded = encode(program)     # SpaceLang whitespace encoding
+tokens = tokenize(encoded)
+decoded_program = parse(tokens)
+```
+
+The package also exports the core `Program`, `Instr`, and `OP` types, along
+with `assemble`, `disassemble`, `encode`, `parse`, and `tokenize` from
+`spacelang`.
+
+## Development
+
+Run the test suite from the repository root:
+
+```bash
+python -m pytest
+```
+
+The tests cover the current IR, encoding/parser, assembler/disassembler, VM,
+Python-subset frontend, and native/reference differential behavior.

spacelanguage-0.1.0/README.md

@@ -0,0 +1,180 @@
+# SpaceLang
+
+SpaceLang is an experimental stack-based language toolkit. It currently
+contains a Python reference VM, an experimental C++ VM, a small Python-subset
+frontend, and tools for assembling, disassembling, and encoding SpaceLang
+programs.
+
+> **Status:** Early development. The frontend and VM implement a subset of
+> Python and the project is not yet a drop-in Python runtime. See the source and
+> tests for the behavior currently supported.
+
+## Requirements
+
+- Python 3.10 or newer
+- A C++17 compiler and CMake 3.18 or newer to build the native extension
+
+## Install
+
+Clone the repository and install it in editable mode:
+
+```bash
+git clone https://github.com/DwwLSM/spacelang.git
+cd spacelang
+python -m pip install -e .
+```
+
+For development, install pytest as well:
+
+```bash
+python -m pip install pytest
+python -m pytest
+```
+
+## Run Python-subset source
+
+Compile supported Python syntax to a SpaceLang program, then execute it with
+the reference VM:
+
+```python
+from spacelang.pyfront import compile_py
+from spacelang.vm_py import VM
+
+source = """
+def add(a, b):
+    return a + b
+
+i = 0
+while i < 3:
+    print(add(i, 2))
+    i = i + 1
+"""
+
+program = compile_py(source)
+VM(program).run()
+```
+
+Output:
+
+```text
+2
+3
+4
+```
+
+The current frontend handles basic integer, boolean, and string constants,
+arithmetic, comparisons, boolean expressions, calls, assignments, supported
+imports, `if`/`else`, `while`, simple positional functions, and `for` loops
+over `range(...)`. Sequence indexing is supported for indexable values.
+
+This is still a Python subset, not full Python; features such as classes,
+exceptions in source code, generators, nested or filtered comprehensions,
+keyword arguments to user functions, and general iterator protocols are not implemented.
+Unsupported syntax raises an error rather than being silently compiled.
+
+## Create a self-copying program
+
+For Python files, `quine` writes a new file with a small hook that copies that
+generated file to a `.copy.py` sibling when run. The input file is left
+unchanged:
+
+```python
+from spacelang.quine import quine
+
+quine("example.py", "example_quine.py")
+```
+
+Then run `python example_quine.py`. The CLI equivalent is:
+
+```bash
+python -m spacelang.quine example.py example_quine.py
+```
+
+The CLI also supports `--in-place --yes`; it creates a `.bak` backup before
+replacing the source. The Python API itself rejects in-place operation.
+SpaceLang `.sp`/`.spz` quines produce a companion `.names.json` file because
+the instruction stream stores name IDs, not their textual names.
+
+## Command-line tools
+
+The command-line interface supports Python compilation, assembly,
+disassembly, execution with the reference VM, and `.sp`/`.spz` compression:
+
+```bash
+python -m spacelang.main compile-py example.py example.sp
+python -m spacelang.main run example.sp
+python -m spacelang.main run example.sp --engine cpp
+python -m spacelang.main disasm example.sp
+python -m spacelang.main pack example.sp
+python -m spacelang.main run example.spz
+```
+
+Compilation enables the safe peephole optimizations and integer constant pool
+by default. Pass `--no-optimize` to `compile-py` to preserve the frontend IR,
+or `--compress-source` to factorize large integer constants before encoding.
+The C++ engine is experimental and is not the default. GCC and Clang builds use
+computed-goto instruction dispatch; other compilers use a portable switch
+dispatcher. Use the Python engine as the reference for behavior that has not
+yet been verified for native parity.
+
+To compare both engines on the same recursive workload after installation:
+
+```bash
+python -m benchmarks.benchmark_vm --n 25 --repeat 3
+```
+
+The benchmark checks that both engines return the same result and reports the
+median runtime and speedup. Timings depend on the host and are not a performance
+guarantee.
+
+## Assemble and run instructions
+
+The assembler accepts one mnemonic instruction per line. For example:
+
+```python
+from spacelang.asm import assemble
+from spacelang.vm_py import VM
+
+program = assemble("""
+PUSH_INT 2
+PUSH_INT 3
+OP 1
+HALT
+""")
+
+print(VM(program).run())
+```
+
+`OP 1` adds the two values on top of the stack. This example prints `5`.
+
+## Inspect and encode programs
+
+```python
+from spacelang.asm import assemble
+from spacelang.disasm import disassemble
+from spacelang.encoder import encode
+from spacelang.lexer import tokenize
+from spacelang.parser import parse
+
+program = assemble("PUSH_INT 2\nPUSH_INT 3\nOP 1\nHALT\n")
+
+print(disassemble(program))   # Human-readable instructions
+encoded = encode(program)     # SpaceLang whitespace encoding
+tokens = tokenize(encoded)
+decoded_program = parse(tokens)
+```
+
+The package also exports the core `Program`, `Instr`, and `OP` types, along
+with `assemble`, `disassemble`, `encode`, `parse`, and `tokenize` from
+`spacelang`.
+
+## Development
+
+Run the test suite from the repository root:
+
+```bash
+python -m pytest
+```
+
+The tests cover the current IR, encoding/parser, assembler/disassembler, VM,
+Python-subset frontend, and native/reference differential behavior.

spacelanguage-0.1.0/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""SpaceLang benchmark utilities."""

spacelanguage-0.1.0/benchmarks/benchmark_vm.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import argparse
+from contextlib import redirect_stdout
+from io import StringIO
+from statistics import median
+from time import perf_counter
+
+from spacelang.pyfront import compile_py
+from spacelang.vm_cpp import VM as CppVM
+from spacelang.vm_py import VM as PythonVM
+
+
+def benchmark_engines(
+    source: str,
+    *,
+    repeats: int = 7,
+    warmup: int = 2,
+    result_name: str | None = "result",
+) -> dict[str, float]:
+    """Return median execution times for CPython and both SpaceLang VMs."""
+    if repeats < 1 or warmup < 0:
+        raise ValueError("repeats must be >= 1 and warmup must be non-negative")
+
+    python_code = compile(source, "<benchmark>", "exec")
+    program = compile_py(source)
+    engine_names = ("CPython", "SP Python", "SP C++")
+    samples = {name: [] for name in engine_names}
+
+    def run_once(engine: str) -> tuple[float, str, object]:
+        output = StringIO()
+        namespace = {"__name__": "__main__"}
+        machine = None
+        if engine == "SP Python":
+            machine = PythonVM(program)
+        elif engine == "SP C++":
+            machine = CppVM(program)
+
+        with redirect_stdout(output):
+            started = perf_counter()
+            if engine == "CPython":
+                exec(python_code, namespace, namespace)
+            else:
+                machine.run()
+            elapsed = perf_counter() - started
+
+        state = namespace if machine is None else machine.globals_
+        if result_name is None:
+            result = None
+        else:
+            if result_name not in state:
+                raise AssertionError(f"{engine} did not set {result_name!r}")
+            result = state[result_name]
+        return elapsed, output.getvalue(), result
+
+    for iteration in range(warmup + repeats):
+        offset = iteration % len(engine_names)
+        order = engine_names[offset:] + engine_names[:offset]
+        measured = {engine: run_once(engine) for engine in order}
+        reference_output = measured["CPython"][1]
+        reference_result = measured["CPython"][2]
+
+        for engine, (_, output, result) in measured.items():
+            if output != reference_output or type(result) is not type(reference_result) or result != reference_result:
+                raise AssertionError(f"{engine} differs from CPython")
+
+        if iteration >= warmup:
+            for engine, (elapsed, _, _) in measured.items():
+                samples[engine].append(elapsed)
+
+    return {engine: median(durations) for engine, durations in samples.items()}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Compare CPython and both SpaceLang VM runtimes.")
+    parser.add_argument("--n", type=int, default=27, help="Fibonacci input (default: 27)")
+    parser.add_argument("--repeat", type=int, default=7, help="Measured runs per engine (default: 7)")
+    parser.add_argument("--warmup", type=int, default=2, help="Unmeasured runs per engine (default: 2)")
+    args = parser.parse_args()
+    if args.n < 0 or args.repeat < 1 or args.warmup < 0:
+        parser.error("--n must be non-negative, --repeat >= 1, and --warmup >= 0")
+
+    source = f"""
+def fib(n):
+    if n < 2:
+        return n
+    return fib(n - 1) + fib(n - 2)
+
+result = fib({args.n})
+"""
+    source = f"""
+
+from math import sqrt
+sum = 0
+for i in range(100000):
+    sum = sqrt(sum) if sum > 20000000 else sqrt(i) * sqrt(3) * 2 + sum
+    
+result = sum    
+    
+"""
+
+
+    durations = benchmark_engines(source, repeats=args.repeat, warmup=args.warmup)
+    baseline = durations["CPython"]
+    for name, duration in durations.items():
+        comparison = "baseline" if name == "CPython" else (
+            f"{baseline / duration:.2f}x faster than CPython"
+            if duration < baseline
+            else f"{duration / baseline:.2f}x slower than CPython"
+        )
+        print(f"{name} median: {duration:.6f}s ({comparison})")
+    print(f"SP C++ vs SP Python: {durations['SP Python'] / durations['SP C++']:.2f}x faster")
+    print("All engines produced matching output and results.")
+
+
+if __name__ == "__main__":
+    main()

spacelanguage-0.1.0/csrc/binding.cpp

@@ -0,0 +1,11 @@
+#include <pybind11/pybind11.h>
+
+#include "vm.hpp"
+
+PYBIND11_MODULE(_spacelang_cpp, module) {
+    pybind11::class_<spacelang::VM>(module, "VM")
+        .def(pybind11::init<pybind11::object>())
+        .def("run", &spacelang::VM::run)
+        .def_property_readonly("stack", &spacelang::VM::stack)
+        .def_property_readonly("globals", &spacelang::VM::globals);
+}

spacelanguage-0.1.0/csrc/ir.hpp

@@ -0,0 +1,14 @@
+#pragma once
+
+#include <cstdint>
+#include <vector>
+
+namespace spacelang {
+
+struct Instr {
+    std::uint8_t op = 0;
+    std::vector<std::int64_t> args;
+    std::int32_t line = 0;
+};
+
+}  // namespace spacelang

spacelanguage-0.1.0/csrc/value.hpp

@@ -0,0 +1,126 @@
+#pragma once
+
+#include <cstdint>
+#include <utility>
+
+#include <Python.h>
+#include <pybind11/pybind11.h>
+
+namespace spacelang {
+
+namespace py = pybind11;
+
+struct Value {
+    enum class Tag : std::uint8_t { INT, FLOAT, BOOL, NONE, PYOBJ };
+
+    union Payload {
+        std::int64_t i;
+        double f;
+        bool b;
+        PyObject* obj;
+
+        Payload() : i(0) {}
+    };
+
+    Tag tag = Tag::NONE;
+    Payload data;
+
+    Value() = default;
+    explicit Value(std::int64_t value) : tag(Tag::INT) { data.i = value; }
+    explicit Value(double value) : tag(Tag::FLOAT) { data.f = value; }
+    explicit Value(bool value) : tag(Tag::BOOL) { data.b = value; }
+
+    static Value from_python(py::handle value) {
+        if (value.is_none()) {
+            return Value();
+        }
+        if (PyBool_Check(value.ptr())) {
+            return Value(value.ptr() == Py_True);
+        }
+        if (PyLong_Check(value.ptr())) {
+            const auto integer = PyLong_AsLongLong(value.ptr());
+            if (PyErr_Occurred()) {
+                PyErr_Clear();
+            } else {
+                return Value(static_cast<std::int64_t>(integer));
+            }
+        }
+        if (PyFloat_Check(value.ptr())) {
+            return Value(PyFloat_AS_DOUBLE(value.ptr()));
+        }
+        Value result;
+        result.tag = Tag::PYOBJ;
+        result.data.obj = value.ptr();
+        Py_INCREF(result.data.obj);
+        return result;
+    }
+
+    Value(const Value& other) : tag(other.tag), data(other.data) {
+        if (tag == Tag::PYOBJ) {
+            Py_INCREF(data.obj);
+        }
+    }
+
+    Value(Value&& other) noexcept : tag(other.tag), data(other.data) {
+        other.tag = Tag::NONE;
+    }
+
+    Value& operator=(Value other) noexcept {
+        swap(other);
+        return *this;
+    }
+
+    ~Value() {
+        if (tag == Tag::PYOBJ) {
+            Py_DECREF(data.obj);
+        }
+    }
+
+    void swap(Value& other) noexcept {
+        const auto temporary = data;
+        data = other.data;
+        other.data = temporary;
+        const auto previous_tag = tag;
+        tag = other.tag;
+        other.tag = previous_tag;
+    }
+
+    py::object to_python() const {
+        switch (tag) {
+            case Tag::INT:
+                return py::int_(data.i);
+            case Tag::FLOAT:
+                return py::float_(data.f);
+            case Tag::BOOL:
+                return py::bool_(data.b);
+            case Tag::NONE:
+                return py::none();
+            case Tag::PYOBJ:
+                return py::reinterpret_borrow<py::object>(data.obj);
+        }
+        throw py::type_error("invalid SpaceLang Value tag");
+    }
+
+    bool truthy() const {
+        switch (tag) {
+            case Tag::INT:
+                return data.i != 0;
+            case Tag::FLOAT:
+                return data.f != 0.0;
+            case Tag::BOOL:
+                return data.b;
+            case Tag::NONE:
+                return false;
+            case Tag::PYOBJ: {
+                const int result = PyObject_IsTrue(data.obj);
+                if (result < 0) {
+                    throw py::error_already_set();
+                }
+                return result != 0;
+            }
+        }
+        return false;
+    }
+};
+
+}  // namespace spacelang