Skip to content

Commit ab9837a

Browse files
docs: Update project docs.
1 parent 89111e8 commit ab9837a

1 file changed

Lines changed: 29 additions & 57 deletions

File tree

documentation/implementation/design.md

Lines changed: 29 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -9,35 +9,6 @@ Edge Python is a compact bytecode compiler and stack VM for a functional subset
99

1010
There is no AST and no IR: bytecode is the only intermediate representation between source and execution.
1111

12-
## Pipeline
13-
14-
```text
15-
source bytes
16-
17-
18-
┌──────────┐
19-
│ Lexer │ LUT-driven scan, offsets into source, soft-keyword resolution
20-
└──────────┘
21-
│ (start, end, kind) tokens
22-
23-
┌──────────┐
24-
│ Parser │ Pratt precedence, SSA versioning, Phi at joins
25-
└──────────┘
26-
│ SSAChunk { instructions, constants, names, functions, classes }
27-
28-
┌──────────┐
29-
│Optimizer │ Constant folding, dead-code compaction, jump remap
30-
└──────────┘
31-
│ same SSAChunk, smaller
32-
33-
┌──────────┐
34-
│ VM │ Token-threaded dispatch, IC, template memoization, mark-sweep GC
35-
└──────────┘
36-
37-
38-
output buffer
39-
```
40-
4112
## Concepts
4213

4314
- **Offset-based tokens**: Tokens carry `(start, end, kind)` indices into the source buffer. No string copies during lexing; identifier and string content is sliced lazily by the parser.
@@ -97,34 +68,35 @@ The heap is an arena of `Option<HeapObj>` slots with a free list. Strings of 64
9768

9869
```text
9970
src/
100-
├── lib.rs
101-
├── main.rs
102-
└── modules/
103-
├── fstr.rs format helpers without core::fmt
104-
├── fx.rs FxHashMap / FxHashSet (no_std hasher)
105-
├── lexer/
106-
│ ├── mod.rs public Token / TokenType, lexer entry
107-
│ ├── scan.rs byte-level scanner state machine
108-
│ └── tables.rs BYTE_CLASS, SINGLE_TOK, keyword LUT
109-
├── parser/
110-
│ ├── mod.rs Parser struct, SSA join logic, error recovery
111-
│ ├── expr.rs Pratt precedence climbing, postfix tails
112-
│ ├── stmt.rs statement dispatch, name_stmt with augmented assign
113-
│ ├── control.rs if / for / while / try / with / match / import
114-
│ ├── literals.rs list / dict / set / fstring / call / params
115-
│ └── types.rs OpCode, SSAChunk, Diagnostic, Value
116-
└── vm/
117-
├── mod.rs VM struct, exec loop, dispatch, GC roots
118-
├── cache.rs OpcodeCache (IC), Templates (memoization), method fusion
119-
├── optimizer.rs constant folding pass + jump remap
120-
├── ops.rs binop kernels, equality, truthiness, type tag
121-
├── types.rs Val, HeapObj, BigInt, DictMap, VmErr, Limits
122-
├── builtins.rs built-in function bodies (print, len, abs, ...)
123-
└── handlers/
124-
├── arith.rs Add, Sub, Mul, Div, Mod, Pow, FloorDiv, Minus, BitOps, Compare, Logic
125-
├── data.rs Store, Build, Container, Comprehension, Yield, Side
126-
├── function.rs Call, MakeFunction, exec_call, dispatch_native
127-
└── methods.rs string / list / dict method tables, dispatch_method
71+
├── main.rs
72+
├── modules
73+
│ ├── fstr.rs
74+
│ ├── fx.rs
75+
│ ├── lexer
76+
│ │ ├── mod.rs
77+
│ │ ├── scan.rs
78+
│ │ └── tables.rs
79+
│ ├── parser
80+
│ │ ├── control.rs
81+
│ │ ├── expr.rs
82+
│ │ ├── literals.rs
83+
│ │ ├── mod.rs
84+
│ │ ├── stmt.rs
85+
│ │ └── types.rs
86+
│ └── vm
87+
│ ├── builtins.rs
88+
│ ├── cache.rs
89+
│ ├── handlers
90+
│ │ ├── arith.rs
91+
│ │ ├── data.rs
92+
│ │ ├── function.rs
93+
│ │ ├── methods.rs
94+
│ │ └── mod.rs
95+
│ ├── mod.rs
96+
│ ├── ops.rs
97+
│ ├── optimizer.rs
98+
│ └── types.rs
99+
└── wasm.rs
128100
```
129101

130102
## Capabilities

0 commit comments

Comments
 (0)