all files

Author: Yonas650

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+#runs pytest on GitHub Actions for push/pr stability
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Run tests
+        run: |
+          pytest

.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+.pytest_cache/
+*.py[cod]
+.DS_Store
+.env
+.venv
+*.egg-info/
+dist/
+build/
+*.bc
+out/

README.md

@@ -1 +1,139 @@
-# decaf-bytecode
+# Decaf: a tiny bytecode-compiled language
+
+Decaf is a lean, portfolio-friendly project that walks from source code to a working bytecode VM:
+
+- hand-written lexer, Pratt-style parser, and AST with source spans
+- semantic resolver with lexical scopes, mutability checks, and call validation
+- bytecode compiler targeting a compact stack machine
+- virtual machine with globals, call frames, tracing, and disassembly tooling
+- CLI for `compile`, `run`, and `disasm`, plus JSON serialization for bytecode artifacts
+
+## Quick start
+
+```bash
+# clone, then install in editable mode with dev tooling
+python -m pip install --upgrade pip
+pip install -e .[dev]
+
+# run the acceptance programs
+decaf run examples/sum_loop.decaf
+
+# inspect the generated bytecode
+decaf disasm examples/sum_loop.decaf
+
+# enable VM tracing while executing
+decaf run examples/sum_loop.decaf --trace
+```
+
+> Working locally without installation? Prefix commands with `PYTHONPATH=src python -m decaf.cli ...` instead.
+
+## Language snapshot
+
+- **Type system**: 32-bit signed integers only; truthiness follows C rules (0 is false, non-zero true).
+- **Declarations**: immutable `let` and mutable `var` at global or block scope; immutables reject reassignment.
+- **Expressions**: integer literals, identifiers, `+ - * /`, parentheses, call expressions.
+- **Statements**: expression statements, `print`, blocks, `if/else`, `while`, and `return`.
+- **Functions**: first-order, positional parameters, lexical scoping, required `return` on every path; `main()` is the entry point.
+
+### Grammar sketch
+
+```
+program   := (fnDecl | varDecl)* EOF
+fnDecl    := "fn" IDENT "(" params? ")" block
+varDecl   := ("let" | "var") IDENT "=" expr ";"
+stmt      := block | "print" expr ";" | ifStmt | whileStmt | returnStmt | expr ";"
+expr      := assignment
+assignment:= IDENT "=" assignment | term
+term      := factor (("+" | "-") factor)*
+factor    := unary (("*" | "/") unary)*
+unary     := "-" unary | call
+```
+
+## Bytecode & VM
+
+The compiler lowers functions into isolated chunks that share a constant pool. Values live on a stack; locals are addressed by slot, globals by index.
+
+| Opcode | Stack effect | Notes |
+| --- | --- | --- |
+| `PUSH_CONST c` | `+1` | push constant index `c` |
+| `LOAD_LOCAL i` / `STORE_LOCAL i` | `±1` | locals live in a contiguous frame |
+| `LOAD_GLOBAL g` / `STORE_GLOBAL g` | `±1` | globals stored in a module-wide array |
+| `ADD`, `SUB`, `MUL`, `DIV` | `-1` | arithmetic pops two values, pushes result (`DIV` truncates toward zero) |
+| `JMP addr` | `0` | unconditional branch |
+| `JMP_IF_FALSE addr` | `-1` | pop condition, jump when zero |
+| `CALL f argc` | `1-argc` | push args left→right, call function `f` |
+| `RET` | `-1` | pop return value, restore caller |
+| `PRINT` | `-1` | pop value, print decimal |
+| `POP` | `-1` | discard top of stack |
+| `HALT` | `0` | stop execution (entry chunk only) |
+
+### Disassembly snapshot
+
+```
+$ decaf disasm examples/sum_loop.decaf
+== fn 0 main ==
+0000 line   2 PUSH_CONST    #0 (0)
+0003 line   2 STORE_LOCAL   0
+0006 line   3 PUSH_CONST    #1 (0)
+0009 line   3 STORE_LOCAL   1
+...
+0053 line   8 LOAD_LOCAL    1
+0056 line   8 PRINT
+0057 line   9 LOAD_LOCAL    1
+0060 line   9 RET
+== fn 1 <entry> ==
+0000 line   1 CALL           0 main argc=0
+0004 line   1 POP
+0005 line   1 HALT
+```
+
+### Trace mode
+
+```
+$ decaf run examples/sum_loop.decaf --trace
+[trace] ip=0 fn=<entry> op=CALL stack=[<empty>]
+[trace] ip=0 fn=main op=PUSH_CONST stack=[0,0]
+[trace] ip=3 fn=main op=STORE_LOCAL stack=[0,0,0]
+...
+[trace] ip=53 fn=main op=LOAD_LOCAL stack=[...,-1,0,5,10]
+[trace] ip=56 fn=main op=PRINT stack=[...,-1,0,5,10,10]
+10
+```
+Trace output shows the instruction pointer, function, opcode, and the tail of the operand stack.
+
+## Examples
+
+| Program | Description | Output |
+| --- | --- | --- |
+| `examples/arithmetic.decaf` | expression precedence and return | `14` |
+| `examples/variables.decaf` | global mutation vs. local `let` | `13` |
+| `examples/if_else.decaf` | conditional execution | `5` |
+| `examples/sum_loop.decaf` | accumulation in a `while` loop | `10` |
+| `examples/factorial.decaf` | recursive function + multiplication | `120` |
+
+## Development
+
+- **Tests**: `pytest` exercises the lexer, parser, resolver, compiler, VM, and serializer. A GitHub Actions workflow runs them on every push/PR targeting `main`.
+- **Formatting**: the project sticks to concise, intentional comments (e.g. `#describes...`) when needed; otherwise the code aims for readability without extra tooling.
+- **Bytecode snapshots**: disassembler output doubles as golden coverage—update the README samples if you tweak the instruction set.
+
+### Suggested workflow
+
+```bash
+# run unit tests
+pytest
+
+# regenerate bytecode JSON for shipping artifacts
+decaf compile examples/sum_loop.decaf -o out/sum_loop.bc
+
+# execute the saved bytecode
+decaf run --bytecode out/sum_loop.bc
+```
+
+## Future ideas
+
+- boolean literals and comparison opcodes that return 0/1
+- simple CFG-aware optimizer (constant folding, dead-branch pruning)
+- bytecode verifier and max-stack precomputation per function
+- structured error diagnostics (source snippets, suggestions)
+- richer value types (strings) once the VM has a heap strategy

examples/arithmetic.decaf

@@ -0,0 +1,5 @@
+//noteshows precedence of arithmetic and return semantics
+fn main() {
+    print 2 + 3 * 4;
+    return 0;
+}

examples/factorial.decaf

@@ -0,0 +1,13 @@
+//noterecursive factorial example stressing calls
+fn fact(n) {
+    if (n - 1) {
+        return n * fact(n - 1);
+    } else {
+        return 1;
+    }
+}
+
+fn main() {
+    print fact(5);
+    return 0;
+}

examples/if_else.decaf

@@ -0,0 +1,13 @@
+//notetests conditional printing via if/else branches
+fn classify(n) {
+    if (n) {
+        print n;
+    } else {
+        print 0;
+    }
+    return n;
+}
+
+fn main() {
+    return classify(5);
+}

examples/sum_loop.decaf

@@ -0,0 +1,11 @@
+//notesums the first five integers using a while loop
+fn main() {
+    var i = 0;
+    var total = 0;
+    while (i - 5) {
+        total = total + i;
+        i = i + 1;
+    }
+    print total;
+    return total;
+}

examples/variables.decaf

@@ -0,0 +1,12 @@
+//notedemonstrates global mutation alongside local let
+var g = 10;
+fn main() {
+    let base = g;
+    var i = 0;
+    while (i - 3) {
+        g = g + i;
+        i = i + 1;
+    }
+    print g;
+    return base;
+}

pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "decaf-bytecode"
+version = "0.1.0"
+authors = [{name = "Your Name"}]
+description = "Decaf: a tiny bytecode-compiled language"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+decaf = "decaf.cli:main"

src/decaf/__init__.py

@@ -0,0 +1,15 @@
+"""Decaf: a tiny bytecode-compiled language."""
+
+#makes package exports explicit for downstream imports
+from . import ast, compiler, disasm, lexer, parser, semantic, token, vm
+
+__all__ = [
+    "ast",
+    "compiler",
+    "disasm",
+    "lexer",
+    "parser",
+    "semantic",
+    "token",
+    "vm",
+]