fromscratch-pebble 0.3.0__py3-none-any.whl

fromscratch_pebble-0.3.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: fromscratch-pebble
+Version: 0.3.0
+Summary: An educational compiler and bytecode VM for the Pebble language
+Project-URL: Homepage, https://github.com/robcox2910/pebble-lang
+Project-URL: Repository, https://github.com/robcox2910/pebble-lang
+Project-URL: Issues, https://github.com/robcox2910/pebble-lang/issues
+Project-URL: Documentation, https://robcox2910.github.io/pebble-lang/
+Author: Rob Cox
+License: MIT
+License-File: LICENSE
+Keywords: bytecode,compiler,education,language,virtual-machine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.4.0; extra == 'dev'
+Requires-Dist: hypothesis>=6.170; extra == 'dev'
+Requires-Dist: pip-audit>=2.10.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.1; extra == 'dev'
+Requires-Dist: pyright>=1.1.400; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff>=0.9.3; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Pebble
+
+An educational compiler and bytecode VM for the **Pebble** programming language.
+
+Pebble is a small imperative language that compiles to bytecode and runs on a
+custom stack-based virtual machine. The project is designed for learning how
+compilers work, built incrementally using TDD.
+
+## Language Features
+
+- Integers, floats, strings, booleans
+- Variables (`let` declarations, `const`, reassignment)
+- Arithmetic, comparison, bitwise, and logical operators (`and`, `or`, `not`)
+- Short-circuiting `and` / `or` and chained comparisons (`1 < x < 10`)
+- Control flow: `if/else`, `while`, `for` loops, `match`
+- Collections: lists, dicts, list comprehensions, slicing, tuple unpacking
+- Functions (`fn`, `return`), default arguments, closures, and generators (`yield`)
+- Async / await (`async fn`, `await`)
+- Structs, classes with inheritance, and enums
+- Error handling: `try` / `catch` / `finally` and `throw`
+- Modules and imports (`import`, `from ... import`)
+- String interpolation (`"hello {name}"`)
+- `print()` built-in
+- Comments (`#`)
+- Curly-brace blocks, newline-delimited statements (no semicolons)
+
+## Example
+
+```
+let count = 0
+while count < 5 {
+    if count > 0 {
+        print(count)
+    }
+    count = count + 1
+}
+```
+
+## Pipeline
+
+```
+Source -> Lexer -> Parser -> Analyzer -> Module Resolver -> Type Checker -> Compiler -> Optimizer -> VM
+```
+
+See the [documentation](https://robcox2910.github.io/pebble-lang/) for a
+kid-friendly walk-through of each stage.
+
+## Quick Start
+
+```bash
+# Install dependencies
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Lint and type check
+uv run ruff check .
+uv run pyright src tests
+```
+
+## Using Pebble from Python
+
+```python
+from pebble import run_source
+
+print(run_source('print("Hello from Pebble!")'), end="")
+```
+
+`run_source`, `compile_source`, `check` and `format_source` are Pebble's public
+API; see [Using Pebble from Python](docs/concepts/using-pebble-from-python.md).
+
+<!-- docs:start -->
+## Documentation
+
+Full docs (with kid-friendly explanations of every idea): https://robcox2910.github.io/pebble-lang/
+<!-- docs:end -->
+
+## Releasing
+
+Other projects in the series ([PyStack](https://github.com/robcox2910/pystack) and [PyLLM](https://github.com/robcox2910/pyllm)) use a pinned release of this one,
+not whatever is on `main`. To publish a change for them:
+
+1. Merge the change to `main`.
+2. Tag it: `git tag -a vX.Y.Z -m vX.Y.Z && git push origin vX.Y.Z`.
+   A change to the public API bumps the minor version (`v0.1.0` → `v0.2.0`);
+   anything else bumps the patch (`v0.1.0` → `v0.1.1`).
+3. In each project that uses it, edit the tag in `[tool.uv.sources]`, run
+   `uv lock --upgrade-package <name>`, and open a pull request so CI checks
+   the pair together.
+
+<!-- series:start -->
+## Related Projects
+
+This project is one of a series that builds real systems "from scratch in Python" to teach how they work. See the [series home](https://robcox2910.github.io/) for the full story.
+
+| Project | What it teaches | Repository | Docs |
+| --- | --- | --- | --- |
+| PyOS | Operating systems | [py-os](https://github.com/robcox2910/py-os) | [Docs](https://robcox2910.github.io/py-os/) |
+| **Pebble** | **Compilers and programming languages** | [pebble-lang](https://github.com/robcox2910/pebble-lang) | [Docs](https://robcox2910.github.io/pebble-lang/) |
+| PyDB | Relational databases | [pydb](https://github.com/robcox2910/pydb) | [Docs](https://robcox2910.github.io/pydb/) |
+| PyKV | Key-value stores | [pykv](https://github.com/robcox2910/pykv) | [Docs](https://robcox2910.github.io/pykv/) |
+| PyDocDB | Document databases | [pydoc-db](https://github.com/robcox2910/pydoc-db) | [Docs](https://robcox2910.github.io/pydoc-db/) |
+| PyGraphDB | Graph databases | [pygraphdb](https://github.com/robcox2910/pygraphdb) | [Docs](https://robcox2910.github.io/pygraphdb/) |
+| PyTSDB | Time-series databases | [pytsdb](https://github.com/robcox2910/pytsdb) | [Docs](https://robcox2910.github.io/pytsdb/) |
+| PyVecDB | Vector databases | [pyvecdb](https://github.com/robcox2910/pyvecdb) | [Docs](https://robcox2910.github.io/pyvecdb/) |
+| PyColDB | Column-family databases | [pycoldb](https://github.com/robcox2910/pycoldb) | [Docs](https://robcox2910.github.io/pycoldb/) |
+| PyCrypt | Cryptography | [pycrypt](https://github.com/robcox2910/pycrypt) | [Docs](https://robcox2910.github.io/pycrypt/) |
+| PyNet | Computer networking | [pynet](https://github.com/robcox2910/pynet) | [Docs](https://robcox2910.github.io/pynet/) |
+| PyWeb | HTTP web servers | [pyweb](https://github.com/robcox2910/pyweb) | [Docs](https://robcox2910.github.io/pyweb/) |
+| PyGit | Version control | [pygit](https://github.com/robcox2910/pygit) | [Docs](https://robcox2910.github.io/pygit/) |
+| PySearch | Search engines | [pysearch](https://github.com/robcox2910/pysearch) | [Docs](https://robcox2910.github.io/pysearch/) |
+| PyMQ | Message queues | [pymq](https://github.com/robcox2910/pymq) | [Docs](https://robcox2910.github.io/pymq/) |
+| PyLLM | Language models (the brain) | [pyllm](https://github.com/robcox2910/pyllm) | [Docs](https://robcox2910.github.io/pyllm/) |
+| PyScheduler | Job scheduling | [pyscheduler](https://github.com/robcox2910/pyscheduler) | [Docs](https://robcox2910.github.io/pyscheduler/) |
+| PyStack | Full-stack integration | [pystack](https://github.com/robcox2910/pystack) | [Docs](https://robcox2910.github.io/pystack/) |
+<!-- series:end -->
+
+## License
+
+MIT

fromscratch_pebble-0.3.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+pebble/__init__.py,sha256=Ia56NojvGKghbK7GZ8UgfF_M7kFEQIB-wPtBfeTCvE0,552
+pebble/__main__.py,sha256=ayKH22F_BPVwXQqa-xBUd0wTSIW0cNvAPugA3nJng4Q,91
+pebble/_pipeline.py,sha256=1tL2o4VxhvFfmKx6d15EvC87dCNc6HHyCZHnN0pmV_w,4653
+pebble/_version.py,sha256=RCY04NY0kBCyn6ttH6lnVL6Gz2gceOrt45f0yDOOU8A,520
+pebble/analyzer.py,sha256=6yDcaNeEORG_9_Y4Vx0VjM0FD1-L2Kp06R-N-lp-tGY,48677
+pebble/api.py,sha256=oK0-PW0OebmUI52LCZ3U_zpjBXOoGZydiMmHw8zZhxM,3755
+pebble/ast_nodes.py,sha256=PzmQWFd2ra8i2byw8NaBTM13184-yY8cg5lJPRtk5cU,15281
+pebble/builtins.py,sha256=naboRWF-ukLAa8moXsW0AUiqBSUfe69jO2SljFvk-Z0,23792
+pebble/bytecode.py,sha256=wktNuLBGqNfP_9Wdr-cmN6WIHIMk9v0l1Yd1pDdKb80,7317
+pebble/cli.py,sha256=_ac25mgldhuAf2SP99L8ELoW5Ejd7TP39HBn04ANNsc,4639
+pebble/compiler.py,sha256=p0PeJrFJEqULHGeHIyKa9UqiQEjXvqcg-fdPoPUesY0,54102
+pebble/debugger.py,sha256=TYdbciU57rZHq0FG_eOqdeEXYHYIr5kExvLHwDNDyFc,13276
+pebble/errors.py,sha256=xvN5IoaqFACz7e8Nx6q_VU1bTA2HgJrW2MaQYatAQ0s,5984
+pebble/formatter.py,sha256=rx_i7nr5aklXkA-1gXE-3RqAYK9RU4H9xzIUP7_q_KI,38361
+pebble/lexer.py,sha256=s1XZq9qn6BHEvB-4VzIm6Jubr19MxUkDomk1RA3tsAw,18458
+pebble/linter.py,sha256=TkPXXWDnumdU9zAGsIX7O-1ki5gJrAkuyj4evMFxOsE,17910
+pebble/optimizer.py,sha256=rh77-2EIeMm5UJhDAcbwzIPeVa-F-rVP4G8mGo6ZAmA,18253
+pebble/parser.py,sha256=5M8YgpmE94udYUYepZrT0R8nTUnxgeFBCxdOB5xRU08,57157
+pebble/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pebble/repl.py,sha256=GWPyubCjtMWLpykw9Kd952z0sbuUUHxdIBzvEU-56-4,7338
+pebble/resolver.py,sha256=tDSdYuW0MTis0jkcenAuIxH346u1pHv724tDlg82UaE,17210
+pebble/stdlib.py,sha256=EsnQaWyWxsPrOzAYO_absj8TlD_71lx_otqjNKJPm8I,6255
+pebble/tokens.py,sha256=qoiFu5e4KCmlIlitbr9AKvSWvAKLVeDOzM0VdT47eFc,4406
+pebble/type_checker.py,sha256=KvZXrOFdep3rcfUMZRfUL6olyXaHqsyxrklyvVkVMu4,20681
+pebble/vm.py,sha256=MKzY-T5rnNKFPfnFk10ONgKKKwWfR4P8rVgXeDdNGCc,74622
+fromscratch_pebble-0.3.0.dist-info/METADATA,sha256=DCsFG-oYTmLkx-GDdkBuygeCSCnhwGJHbzfmmEcYTGA,6906
+fromscratch_pebble-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fromscratch_pebble-0.3.0.dist-info/entry_points.txt,sha256=S4qheUTGQBJUiEuAwBs5XgRXURTeKCTv-QuDzeBonso,43
+fromscratch_pebble-0.3.0.dist-info/licenses/LICENSE,sha256=NtHM2ak--oE71VCcY50kcCoC1cKS0LRUsxq_xA89RNc,1064
+fromscratch_pebble-0.3.0.dist-info/RECORD,,

fromscratch_pebble-0.3.0.dist-info/WHEEL

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

fromscratch_pebble-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pebble = pebble.cli:main

fromscratch_pebble-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Cox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pebble/__init__.py

@@ -0,0 +1,22 @@
+"""Pebble - An educational compiler and bytecode VM.
+
+The names below are Pebble's public API: the ones promised to stay the same
+between versions. See :mod:`pebble.api`.
+"""
+
+from pebble._pipeline import Program
+from pebble.api import check, compile_source, format_source, run_source
+from pebble.builtins import Value
+from pebble.errors import PebbleError
+from pebble.stdlib import StdlibModule
+
+__all__ = [
+    "PebbleError",
+    "Program",
+    "StdlibModule",
+    "Value",
+    "check",
+    "compile_source",
+    "format_source",
+    "run_source",
+]

pebble/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running Pebble with ``python -m pebble``."""
+
+from pebble.cli import main
+
+main()

pebble/_pipeline.py

@@ -0,0 +1,137 @@
+"""The one place Pebble's pieces are wired together into a runnable program.
+
+Private: use :mod:`pebble.api` instead. The ``pebble`` command and the
+public API both build programs here, so the wiring is written once.
+"""
+
+import io
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TextIO, override
+
+from pebble.analyzer import SemanticAnalyzer
+from pebble.builtins import Value
+from pebble.bytecode import CompiledProgram
+from pebble.compiler import Compiler
+from pebble.lexer import Lexer
+from pebble.optimizer import optimize
+from pebble.parser import Parser
+from pebble.resolver import ModuleResolver
+from pebble.stdlib import StdlibHandler, StdlibModule
+from pebble.type_checker import type_check
+from pebble.vm import DebugHook, VirtualMachine
+
+type StdlibHandlers = dict[str, tuple[int | tuple[int, ...], StdlibHandler]]
+
+
+class _Capture(io.StringIO):
+    """Collect everything a program prints, copying it to *echo* as it goes."""
+
+    def __init__(self, echo: TextIO | None) -> None:
+        super().__init__()
+        self._echo = echo
+
+    @override
+    def write(self, s: str, /) -> int:
+        if self._echo is not None:
+            self._echo.write(s)
+        return super().write(s)
+
+    @override
+    def flush(self) -> None:
+        if self._echo is not None:
+            self._echo.flush()
+
+
+@dataclass(frozen=True)
+class Program:
+    """A checked, compiled Pebble program, ready to run as many times as you like.
+
+    Make one with :func:`pebble.compile_source`. It remembers its own
+    modules, so running it never looks anything up in a shared table.
+    Its attributes are Pebble internals and may change between versions;
+    :meth:`run` is the promised way to use it.
+    """
+
+    compiled: CompiledProgram
+    stdlib_handlers: StdlibHandlers
+    stdlib_constants: dict[str, Value]
+
+    def run(self, output: TextIO | None = None) -> str:
+        """Run the program and return everything it printed.
+
+        Args:
+            output: Also write the printed text here as it happens
+                (for example ``sys.stdout``). Optional.
+
+        Returns:
+            Everything the program printed.
+
+        Raises:
+            PebbleRuntimeError: If the program fails while running.
+
+        """
+        return run_program(self, output)
+
+
+def run_program(
+    program: Program, output: TextIO | None, debug_hook: DebugHook | None = None
+) -> str:
+    """Run *program*, optionally with a debugger attached (used by ``pebble --debug``)."""
+    capture = _Capture(output)
+    VirtualMachine(output=capture).run(
+        program.compiled,
+        stdlib_handlers=program.stdlib_handlers,
+        stdlib_constants=program.stdlib_constants,
+        debug_hook=debug_hook,
+    )
+    return capture.getvalue()
+
+
+def compile_program(source: str, *, modules: Mapping[str, StdlibModule], base_dir: Path) -> Program:
+    """Lex, parse, analyze, type-check, compile and optimize *source*.
+
+    Args:
+        source: The Pebble program.
+        modules: Every importable module by name (built-ins included).
+        base_dir: Where ``import "file.pbl"`` looks for files.
+
+    Returns:
+        The runnable program.
+
+    """
+    program = Parser(Lexer(source).tokenize()).parse()
+    analyzer = SemanticAnalyzer()
+    resolver = ModuleResolver(base_dir=base_dir, modules=modules)
+    resolver.resolve_imports(program, analyzer)
+    analyzed = analyzer.analyze(program)
+    type_check(analyzed, analyzer=analyzer)
+    compiled = Compiler(
+        cell_vars=analyzer.cell_vars,
+        free_vars=analyzer.free_vars,
+        enums=resolver.merged_enums,
+        class_parents=resolver.merged_class_parents,
+        structs=resolver.merged_structs,
+        class_methods=resolver.merged_class_methods,
+        functions=resolver.merged_functions,
+        variable_arity_functions=resolver.variable_arity_functions,
+    ).compile(analyzed)
+    compiled = optimize(compiled)
+    full_program = CompiledProgram(
+        main=compiled.main,
+        functions={**resolver.merged_functions, **compiled.functions},
+        structs={**resolver.merged_structs, **compiled.structs},
+        struct_field_types={
+            **resolver.merged_struct_field_types,
+            **compiled.struct_field_types,
+        },
+        class_methods={**resolver.merged_class_methods, **compiled.class_methods},
+        enums={**resolver.merged_enums, **compiled.enums},
+        class_parents={**resolver.merged_class_parents, **compiled.class_parents},
+    )
+    return Program(
+        full_program,
+        dict(resolver.merged_stdlib_handlers),
+        dict(resolver.merged_stdlib_constants),
+    )

pebble/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = None