add PBS docs
This commit is contained in:
@@ -0,0 +1,359 @@
|
||||
# PBS v0 Canonical Addenda
|
||||
|
||||
> **Purpose:** eliminate ambiguity for Junie and for golden tests.
|
||||
>
|
||||
> This document is **normative** for PBS Frontend v0 and complements:
|
||||
>
|
||||
> * **PBS Frontend Spec v0 — Implementer Edition**
|
||||
> * **Junie PR Plan**
|
||||
>
|
||||
> These addenda define:
|
||||
>
|
||||
> 1. operator precedence & associativity
|
||||
> 2. canonical AST JSON shape (v0)
|
||||
> 3. canonical diagnostic codes (v0)
|
||||
|
||||
---
|
||||
|
||||
## 1) Operator Precedence and Associativity (v0)
|
||||
|
||||
### 1.1 Guiding rule
|
||||
|
||||
PBS v0 prioritizes **minimal ambiguity** and **easy parsing**.
|
||||
|
||||
* Most operators are **left-associative**.
|
||||
* Assignment is **not** an expression in v0 (no `=` operator expressions).
|
||||
* Member access and indexing are not part of v0 surface syntax unless already defined elsewhere.
|
||||
|
||||
### 1.2 Precedence table
|
||||
|
||||
From **highest** to **lowest**:
|
||||
|
||||
1. **Primary**
|
||||
|
||||
* literals (`10`, `3.14`, `"text"`, `none`, `some(x)`, `ok(x)`, `err(e)`)
|
||||
* identifiers (`foo`)
|
||||
* parenthesized expression (`(expr)`)
|
||||
* block expression (`{ ... }`) (when allowed as `Expr`)
|
||||
|
||||
2. **Call** (left-associative)
|
||||
|
||||
* `callee(arg1, arg2, ...)`
|
||||
|
||||
3. **Unary prefix** (right-associative)
|
||||
|
||||
* `-expr`
|
||||
* `!expr`
|
||||
* `as` casts are **not unary**; see level 6.
|
||||
|
||||
4. **Multiplicative** (left-associative)
|
||||
|
||||
* `*`, `/`, `%`
|
||||
|
||||
5. **Additive** (left-associative)
|
||||
|
||||
* `+`, `-`
|
||||
|
||||
6. **Cast** (left-associative)
|
||||
|
||||
* `expr as Type`
|
||||
|
||||
7. **Comparison** (non-associative)
|
||||
|
||||
* `<`, `<=`, `>`, `>=`
|
||||
|
||||
8. **Equality** (non-associative)
|
||||
|
||||
* `==`, `!=`
|
||||
|
||||
9. **Logical AND** (left-associative)
|
||||
|
||||
* `&&`
|
||||
|
||||
10. **Logical OR** (left-associative)
|
||||
|
||||
* `||`
|
||||
|
||||
11. **Control expressions** (special)
|
||||
|
||||
* `if ... { ... } else { ... }` (expression form only if your v0 allows it; otherwise statement)
|
||||
* `when { ... }` (expression)
|
||||
|
||||
### 1.3 Non-associative rule
|
||||
|
||||
Comparison and equality are **non-associative**:
|
||||
|
||||
* `a < b < c` is an error
|
||||
* `a == b == c` is an error
|
||||
|
||||
Diagnostic: `E_PARSE_NON_ASSOC`.
|
||||
|
||||
### 1.4 Notes on `when`
|
||||
|
||||
`when` binds weaker than all binary operators.
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
let x = a + b when { ... };
|
||||
```
|
||||
|
||||
Parses as:
|
||||
|
||||
```
|
||||
let x = (a + b) when { ... };
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2) Canonical AST JSON (v0)
|
||||
|
||||
### 2.1 Canonicalization goals
|
||||
|
||||
Canonical AST JSON is used for:
|
||||
|
||||
* golden tests
|
||||
* frontend determinism validation
|
||||
* diff-friendly debugging
|
||||
|
||||
Rules:
|
||||
|
||||
* JSON keys are **stable** and **ordered** (when writing JSON)
|
||||
* All nodes include `kind` and `span`
|
||||
* Spans are byte offsets into the file content
|
||||
|
||||
### 2.2 Span encoding
|
||||
|
||||
```json
|
||||
{"file":"main.pbs","start":12,"end":18}
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
* `start` is inclusive
|
||||
* `end` is exclusive
|
||||
|
||||
### 2.3 Root
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "File",
|
||||
"span": {"file":"...","start":0,"end":123},
|
||||
"imports": [ ... ],
|
||||
"decls": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 Import node
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "Import",
|
||||
"span": {"file":"...","start":0,"end":20},
|
||||
"spec": {"kind":"ImportSpec","path":["Foo","Bar"]},
|
||||
"from": "./lib.pbs"
|
||||
}
|
||||
```
|
||||
|
||||
`ImportSpec.path` is an array of identifiers.
|
||||
|
||||
### 2.5 Declarations
|
||||
|
||||
#### 2.5.1 Service
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "ServiceDecl",
|
||||
"span": {"file":"...","start":0,"end":50},
|
||||
"vis": "pub",
|
||||
"name": "Audio",
|
||||
"extends": null,
|
||||
"members": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
A service member (method signature only in v0):
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "ServiceFnSig",
|
||||
"span": {"file":"...","start":0,"end":10},
|
||||
"name": "play",
|
||||
"params": [ {"name":"sound","ty": {"kind":"TypeName","name":"Sound"}} ],
|
||||
"ret": {"kind":"TypeName","name":"void"}
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.5.2 Function
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "FnDecl",
|
||||
"span": {"file":"...","start":0,"end":80},
|
||||
"name": "main",
|
||||
"params": [],
|
||||
"ret": null,
|
||||
"else": null,
|
||||
"body": {"kind":"Block", ... }
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.5.3 TypeDecl (struct/contract/error)
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "TypeDecl",
|
||||
"span": {"file":"...","start":0,"end":100},
|
||||
"vis": "pub",
|
||||
"typeKind": "struct",
|
||||
"name": "Vector",
|
||||
"body": {"kind":"TypeBody","members":[ ... ]}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.6 Blocks and statements
|
||||
|
||||
Block:
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "Block",
|
||||
"span": {"file":"...","start":0,"end":20},
|
||||
"stmts": [ ... ],
|
||||
"tail": null
|
||||
}
|
||||
```
|
||||
|
||||
* `stmts` are statements.
|
||||
* `tail` is an optional final expression (only if your parser supports expression blocks).
|
||||
|
||||
Statement kinds (v0 minimum):
|
||||
|
||||
* `LetStmt`
|
||||
* `ExprStmt`
|
||||
* `ReturnStmt`
|
||||
|
||||
Let:
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "LetStmt",
|
||||
"span": {"file":"...","start":0,"end":20},
|
||||
"name": "x",
|
||||
"isMut": false,
|
||||
"ty": null,
|
||||
"init": {"kind":"IntLit", "value": 10, "span": ...}
|
||||
}
|
||||
```
|
||||
|
||||
Return:
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "ReturnStmt",
|
||||
"span": {"file":"...","start":0,"end":10},
|
||||
"expr": null
|
||||
}
|
||||
```
|
||||
|
||||
### 2.7 Expressions
|
||||
|
||||
All expressions include `kind` and `span`.
|
||||
|
||||
Minimal v0 expression node kinds:
|
||||
|
||||
* `IntLit` `{ value: i64 }`
|
||||
* `FloatLit` `{ value: f64 }`
|
||||
* `BoundedLit` `{ value: u32 }`
|
||||
* `StringLit` `{ value: string }`
|
||||
* `Ident` `{ name: string }`
|
||||
* `Call` `{ callee: Expr, args: Expr[] }`
|
||||
* `Unary` `{ op: "-"|"!", expr: Expr }`
|
||||
* `Binary` `{ op: string, left: Expr, right: Expr }`
|
||||
* `Cast` `{ expr: Expr, ty: TypeRef }`
|
||||
* `IfExpr` `{ cond: Expr, then: Block, els: Block }` (if expression is supported)
|
||||
* `WhenExpr` `{ arms: WhenArm[] }`
|
||||
|
||||
Type references:
|
||||
|
||||
```json
|
||||
{"kind":"TypeName","name":"int"}
|
||||
```
|
||||
|
||||
Generics:
|
||||
|
||||
```json
|
||||
{"kind":"TypeApp","base":"optional","args":[{"kind":"TypeName","name":"int"}]}
|
||||
```
|
||||
|
||||
### 2.8 Canonical JSON ordering
|
||||
|
||||
When writing AST JSON, always order fields as:
|
||||
|
||||
1. `kind`
|
||||
2. `span`
|
||||
3. semantic fields (stable order)
|
||||
|
||||
This makes diffs deterministic.
|
||||
|
||||
---
|
||||
|
||||
## 3) Diagnostic Codes (v0)
|
||||
|
||||
### 3.1 Diagnostic format
|
||||
|
||||
All diagnostics must be serializable to canonical JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"severity": "error",
|
||||
"code": "E_PARSE_UNEXPECTED_TOKEN",
|
||||
"message": "Unexpected token '}'",
|
||||
"span": {"file":"main.pbs","start":12,"end":13}
|
||||
}
|
||||
```
|
||||
|
||||
Severity is one of: `error`, `warning`.
|
||||
|
||||
### 3.2 Parse/Lex errors (E_PARSE_*)
|
||||
|
||||
* `E_LEX_INVALID_CHAR` — invalid character
|
||||
* `E_LEX_UNTERMINATED_STRING` — string literal not closed
|
||||
* `E_PARSE_UNEXPECTED_TOKEN` — token not expected in current context
|
||||
* `E_PARSE_EXPECTED_TOKEN` — missing required token
|
||||
* `E_PARSE_NON_ASSOC` — chained comparison/equality (non-associative)
|
||||
|
||||
### 3.3 Symbol/Resolve errors (E_RESOLVE_*)
|
||||
|
||||
* `E_RESOLVE_UNDEFINED` — undefined identifier
|
||||
* `E_RESOLVE_DUPLICATE_SYMBOL` — duplicate symbol in same namespace
|
||||
* `E_RESOLVE_NAMESPACE_COLLISION` — name exists in both type and value namespaces
|
||||
* `E_RESOLVE_VISIBILITY` — symbol not visible from this scope/module
|
||||
* `E_RESOLVE_INVALID_IMPORT` — import spec/path invalid
|
||||
|
||||
### 3.4 Type errors (E_TYPE_*)
|
||||
|
||||
* `E_TYPE_MISMATCH` — type mismatch
|
||||
* `E_TYPE_UNKNOWN_TYPE` — unknown type name
|
||||
* `E_TYPE_MUTABILITY` — mutability violation
|
||||
* `E_TYPE_RETURN_PATH` — not all paths return a value
|
||||
* `E_TYPE_INVALID_CAST` — invalid cast
|
||||
|
||||
### 3.5 Lowering errors (E_LOWER_*)
|
||||
|
||||
* `E_LOWER_UNSUPPORTED` — feature not supported in v0 lowering
|
||||
|
||||
### 3.6 Warnings (W_*)
|
||||
|
||||
Warnings are allowed in v0 but should be used sparingly.
|
||||
|
||||
* `W_UNUSED_LET` — unused local binding
|
||||
* `W_SHADOWING` — local shadows another binding
|
||||
|
||||
---
|
||||
|
||||
## Implementation Notes (Non-normative)
|
||||
|
||||
* Keep these addenda in `spec/` in the repo.
|
||||
* Use them to drive golden tests for AST and diagnostics.
|
||||
* If a future change alters canonical AST, bump a version and regenerate goldens deliberately.
|
||||
@@ -0,0 +1,357 @@
|
||||
# PBS Compiler — Junie PR Plan
|
||||
|
||||
> **Purpose:** this document defines a sequence of small, focused Pull Requests to be implemented by *Junie*, one at a time.
|
||||
>
|
||||
> **Audience:** compiler implementer (AI or human).
|
||||
>
|
||||
> **Scope:** PBS-first compiler architecture. TS and Lua frontends are assumed **removed**.
|
||||
>
|
||||
> **Hard rules:**
|
||||
>
|
||||
> * Each PR must compile and pass tests.
|
||||
> * Each PR must include tests.
|
||||
> * No speculative features.
|
||||
> * Follow the `Prometeu Base Script (PBS) - Implementation Spec`.
|
||||
|
||||
---
|
||||
|
||||
## Global Architectural Direction (Non-negotiable)
|
||||
|
||||
* PBS is the **primary language**.
|
||||
* Frontend is implemented **before** runtime integration.
|
||||
* Architecture uses **two IR layers**:
|
||||
|
||||
* **Core IR** (PBS-semantic, typed, resolved)
|
||||
* **VM IR** (stack-based, backend-friendly)
|
||||
* VM IR remains simple and stable.
|
||||
* Lowering is explicit and testable.
|
||||
|
||||
---
|
||||
|
||||
# PR-01 — ProjectConfig and Frontend Selection
|
||||
|
||||
### Goal
|
||||
|
||||
Introduce a project-level configuration that selects the frontend and entry file explicitly.
|
||||
|
||||
### Motivation
|
||||
|
||||
The compiler must not hardcode entry points or languages. PBS will be the first frontend, others may return later.
|
||||
|
||||
### Scope
|
||||
|
||||
* Add `ProjectConfig` (serde-deserializable) loaded from `prometeu.json`
|
||||
* Fields (v0):
|
||||
|
||||
* `script_fe: "pbs"`
|
||||
* `entry: "main.pbs"`
|
||||
* Refactor compiler entry point to:
|
||||
|
||||
* load config
|
||||
* select frontend by `script_fe`
|
||||
* resolve entry path relative to project root
|
||||
|
||||
### Files Likely Touched
|
||||
|
||||
* `compiler/mod.rs`
|
||||
* `compiler/driver.rs`
|
||||
* `common/config.rs` (new)
|
||||
|
||||
### Tests (mandatory)
|
||||
|
||||
* unit test: load valid `prometeu.json`
|
||||
* unit test: invalid frontend → diagnostic
|
||||
* integration test: project root + entry resolution
|
||||
|
||||
### Notes to Junie
|
||||
|
||||
Do **not** add PBS parsing yet. This PR is infrastructure only.
|
||||
|
||||
---
|
||||
|
||||
# PR-02 — Core IR Skeleton (PBS-first)
|
||||
|
||||
### Goal
|
||||
|
||||
Introduce a **Core IR** layer independent from the VM IR.
|
||||
|
||||
### Motivation
|
||||
|
||||
PBS semantics must be represented before lowering to VM instructions.
|
||||
|
||||
### Scope
|
||||
|
||||
* Add new module: `ir_core`
|
||||
* Define minimal structures:
|
||||
|
||||
* `Program`
|
||||
* `Module`
|
||||
* `Function`
|
||||
* `Block`
|
||||
* `Instr`
|
||||
* `Terminator`
|
||||
* IDs only (no string-based calls):
|
||||
|
||||
* `FunctionId`
|
||||
* `ConstId`
|
||||
* `TypeId`
|
||||
|
||||
### Constraints
|
||||
|
||||
* Core IR must NOT reference VM opcodes
|
||||
* No lowering yet
|
||||
|
||||
### Tests
|
||||
|
||||
* construct Core IR manually in tests
|
||||
* snapshot test (JSON) for deterministic shape
|
||||
|
||||
---
|
||||
|
||||
# PR-03 — Constant Pool and IDs
|
||||
|
||||
### Goal
|
||||
|
||||
Introduce a stable constant pool shared by Core IR and VM IR.
|
||||
|
||||
### Scope
|
||||
|
||||
* Add `ConstPool`:
|
||||
|
||||
* strings
|
||||
* numbers
|
||||
* Replace inline literals in VM IR with `ConstId`
|
||||
* Update existing VM IR to accept `PushConst(ConstId)`
|
||||
|
||||
### Tests
|
||||
|
||||
* const pool deduplication
|
||||
* deterministic ConstId assignment
|
||||
* IR snapshot stability
|
||||
|
||||
---
|
||||
|
||||
# PR-04 — VM IR Cleanup (Stabilization)
|
||||
|
||||
### Goal
|
||||
|
||||
Stabilize VM IR as a **lowering target**, not a language IR.
|
||||
|
||||
### Scope
|
||||
|
||||
* Replace string-based calls with `FunctionId`
|
||||
* Ensure locals are accessed via slots
|
||||
* Remove or internalize `PushScope` / `PopScope`
|
||||
|
||||
### Tests
|
||||
|
||||
* golden VM IR tests
|
||||
* lowering smoke test (Core IR → VM IR)
|
||||
|
||||
---
|
||||
|
||||
# PR-05 — Core IR → VM IR Lowering Pass
|
||||
|
||||
### Goal
|
||||
|
||||
Implement the lowering pass from Core IR to VM IR.
|
||||
|
||||
### Scope
|
||||
|
||||
* New module: `lowering/core_to_vm.rs`
|
||||
* Lowering rules:
|
||||
|
||||
* Core blocks → labels
|
||||
* Core calls → VM calls
|
||||
* Host calls preserved
|
||||
* No PBS frontend yet
|
||||
|
||||
### Tests
|
||||
|
||||
* lowering correctness
|
||||
* instruction ordering
|
||||
* label resolution
|
||||
|
||||
---
|
||||
|
||||
# PR-06 — PBS Frontend: Lexer
|
||||
|
||||
### Goal
|
||||
|
||||
Implement PBS lexer according to the spec.
|
||||
|
||||
### Scope
|
||||
|
||||
* Token kinds
|
||||
* Keyword table
|
||||
* Span tracking
|
||||
|
||||
### Tests
|
||||
|
||||
* tokenization tests
|
||||
* keyword vs identifier tests
|
||||
* bounded literals
|
||||
|
||||
---
|
||||
|
||||
# PR-07 — PBS Frontend: Parser (Raw AST)
|
||||
|
||||
### Goal
|
||||
|
||||
Parse PBS source into a raw AST.
|
||||
|
||||
### Scope
|
||||
|
||||
* Imports
|
||||
* Top-level declarations
|
||||
* Blocks
|
||||
* Expressions (calls, literals, control flow)
|
||||
|
||||
### Tests
|
||||
|
||||
* valid programs
|
||||
* syntax error recovery
|
||||
|
||||
---
|
||||
|
||||
# PR-08 — PBS Frontend: Symbol Collection and Resolver
|
||||
|
||||
### Goal
|
||||
|
||||
Resolve names, modules, and visibility.
|
||||
|
||||
### Scope
|
||||
|
||||
* Type namespace vs value namespace
|
||||
* Visibility rules
|
||||
* Import resolution
|
||||
|
||||
### Tests
|
||||
|
||||
* duplicate symbols
|
||||
* invalid imports
|
||||
* visibility errors
|
||||
|
||||
---
|
||||
|
||||
# PR-09 — PBS Frontend: Type Checking
|
||||
|
||||
### Goal
|
||||
|
||||
Validate PBS semantics.
|
||||
|
||||
### Scope
|
||||
|
||||
* Primitive types
|
||||
* Structs
|
||||
* `optional<T>` and `result<T, E>`
|
||||
* Mutability rules
|
||||
* Return path validation
|
||||
|
||||
### Tests
|
||||
|
||||
* type mismatch
|
||||
* mutability violations
|
||||
* implicit `none` behavior
|
||||
|
||||
---
|
||||
|
||||
# PR-10 — PBS Frontend: Semantic Lowering to Core IR
|
||||
|
||||
### Goal
|
||||
|
||||
Lower typed PBS AST into Core IR.
|
||||
|
||||
### Scope
|
||||
|
||||
* ID-based calls
|
||||
* ConstPool usage
|
||||
* Control flow lowering
|
||||
* SAFE vs HIP effects represented explicitly
|
||||
|
||||
### Tests
|
||||
|
||||
* PBS → Core IR snapshots
|
||||
* semantic correctness
|
||||
|
||||
---
|
||||
|
||||
# PR-11 — Host-bound Contracts and Syscall Mapping
|
||||
|
||||
### Goal
|
||||
|
||||
Connect PBS host-bound contracts to runtime syscalls (without executing them).
|
||||
|
||||
### Scope
|
||||
|
||||
* Contract registry
|
||||
* Mapping: contract.method → syscall id
|
||||
* Core IR host call nodes
|
||||
|
||||
### Tests
|
||||
|
||||
* invalid contract calls
|
||||
* correct syscall mapping
|
||||
|
||||
---
|
||||
|
||||
# PR-12 — Diagnostics Canonicalization
|
||||
|
||||
### Goal
|
||||
|
||||
Standardize diagnostics output.
|
||||
|
||||
### Scope
|
||||
|
||||
* Error codes (`E_*`, `W_*`)
|
||||
* Stable messages
|
||||
* Span accuracy
|
||||
|
||||
### Tests
|
||||
|
||||
* golden diagnostics
|
||||
|
||||
---
|
||||
|
||||
# PR-13 — Backend Integration (VM IR → Bytecode)
|
||||
|
||||
### Goal
|
||||
|
||||
Reconnect the pipeline to the Prometeu runtime backend.
|
||||
|
||||
### Scope
|
||||
|
||||
* VM IR → bytecode emission
|
||||
* No PBS semantics here
|
||||
|
||||
### Tests
|
||||
|
||||
* bytecode emission smoke test
|
||||
|
||||
---
|
||||
|
||||
# PR-14 — End-to-End PBS Compile Test
|
||||
|
||||
### Goal
|
||||
|
||||
Prove the full pipeline works.
|
||||
|
||||
### Scope
|
||||
|
||||
* Sample PBS project
|
||||
* Compile → bytecode
|
||||
* Diagnostics only (no execution)
|
||||
|
||||
### Tests
|
||||
|
||||
* golden bytecode snapshot
|
||||
|
||||
---
|
||||
|
||||
## Final Note to Junie
|
||||
|
||||
Do **not** skip PRs.
|
||||
Do **not** merge multiple PRs together.
|
||||
If the spec is unclear, create a failing test and document the ambiguity.
|
||||
|
||||
This plan is the authoritative roadmap for PBS frontend implementation.
|
||||
@@ -0,0 +1,446 @@
|
||||
# Prometeu Base Script (PBS)
|
||||
|
||||
## Frontend Spec v0 — Implementer Edition
|
||||
|
||||
> **Normative specification for building a PBS frontend (lexer, parser, AST, resolver, typechecker) targeting the Prometeu Fantasy Console runtime.**
|
||||
>
|
||||
> This document is **not** a user guide.
|
||||
> It exists to make PBS *implementable*, *deterministic*, and *testable*.
|
||||
|
||||
---
|
||||
|
||||
## 0. Scope and Non‑Goals
|
||||
|
||||
### 0.1 Scope
|
||||
|
||||
This specification defines:
|
||||
|
||||
* lexical structure (tokens)
|
||||
* grammar and parsing rules
|
||||
* canonical AST shapes
|
||||
* frontend phases and their responsibilities
|
||||
* name resolution and visibility rules
|
||||
* type system rules
|
||||
* desugaring and lowering rules
|
||||
* diagnostic categories (errors vs warnings)
|
||||
* required guarantees for runtime integration
|
||||
|
||||
The goal is that **two independent frontends** built from this spec:
|
||||
|
||||
* accept the same programs
|
||||
* reject the same programs
|
||||
* produce equivalent ASTs
|
||||
* emit equivalent diagnostics
|
||||
|
||||
### 0.2 Non‑Goals
|
||||
|
||||
This spec does **not** define:
|
||||
|
||||
* runtime performance characteristics
|
||||
* bytecode layout
|
||||
* JIT or interpreter design
|
||||
* editor tooling or IDE features
|
||||
|
||||
Those are explicitly out of scope.
|
||||
|
||||
---
|
||||
|
||||
## 1. Frontend Pipeline Overview
|
||||
|
||||
A PBS frontend **must** be structured as the following pipeline:
|
||||
|
||||
```
|
||||
Source Text
|
||||
↓
|
||||
Lexer
|
||||
↓
|
||||
Parser
|
||||
↓
|
||||
Raw AST
|
||||
↓
|
||||
Symbol Collection
|
||||
↓
|
||||
Resolver
|
||||
↓
|
||||
Typed AST
|
||||
↓
|
||||
Desugaring / Lowering
|
||||
↓
|
||||
Runtime‑ready IR / AST
|
||||
```
|
||||
|
||||
Each stage has **strict responsibilities**.
|
||||
No stage may perform work assigned to a later stage.
|
||||
|
||||
---
|
||||
|
||||
## 2. Lexical Structure
|
||||
|
||||
### 2.1 Tokens
|
||||
|
||||
A PBS lexer must recognize at minimum the following token classes:
|
||||
|
||||
* identifiers
|
||||
* keywords
|
||||
* numeric literals
|
||||
* string literals
|
||||
* punctuation
|
||||
* operators
|
||||
* comments
|
||||
|
||||
Whitespace is insignificant except as a separator.
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Keywords (Reserved)
|
||||
|
||||
The following keywords are **reserved** and may not be used as identifiers:
|
||||
|
||||
```
|
||||
import
|
||||
pub
|
||||
mod
|
||||
service
|
||||
fn
|
||||
let
|
||||
mut
|
||||
declare
|
||||
struct
|
||||
contract
|
||||
host
|
||||
error
|
||||
optional
|
||||
result
|
||||
some
|
||||
none
|
||||
ok
|
||||
err
|
||||
if
|
||||
else
|
||||
when
|
||||
for
|
||||
in
|
||||
return
|
||||
handle
|
||||
borrow
|
||||
mutate
|
||||
peek
|
||||
take
|
||||
alloc
|
||||
weak
|
||||
as
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.3 Literals
|
||||
|
||||
#### Numeric Literals
|
||||
|
||||
* `int` — decimal digits
|
||||
* `float` — decimal with `.`
|
||||
* `bounded` — decimal digits suffixed with `b`
|
||||
|
||||
Examples:
|
||||
|
||||
```pbs
|
||||
10
|
||||
42
|
||||
3.14
|
||||
0b
|
||||
255b
|
||||
```
|
||||
|
||||
#### String Literals
|
||||
|
||||
* delimited by `"`
|
||||
* UTF‑8 encoded
|
||||
* immutable
|
||||
|
||||
---
|
||||
|
||||
### 2.4 Comments
|
||||
|
||||
* line comment: `// until end of line`
|
||||
* block comments are **not supported** in v0
|
||||
|
||||
---
|
||||
|
||||
## 3. Grammar (EBNF‑style)
|
||||
|
||||
> This grammar is **normative** but simplified for readability.
|
||||
> Implementers may refactor internally as long as semantics are preserved.
|
||||
|
||||
### 3.1 File Structure
|
||||
|
||||
```
|
||||
File ::= Import* TopLevelDecl*
|
||||
Import ::= 'import' ImportSpec 'from' StringLiteral
|
||||
TopLevelDecl::= TypeDecl | ServiceDecl | FnDecl
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Type Declarations
|
||||
|
||||
```
|
||||
TypeDecl ::= Visibility? 'declare' TypeKind Identifier TypeBody
|
||||
TypeKind ::= 'struct' | 'contract' | 'error'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.3 Services
|
||||
|
||||
```
|
||||
ServiceDecl ::= Visibility 'service' Identifier (':' Identifier)? Block
|
||||
```
|
||||
|
||||
Visibility is mandatory for services.
|
||||
|
||||
---
|
||||
|
||||
### 3.4 Functions
|
||||
|
||||
```
|
||||
FnDecl ::= 'fn' Identifier ParamList ReturnType? ElseFallback? Block
|
||||
```
|
||||
|
||||
Top‑level `fn` are always file‑private.
|
||||
|
||||
---
|
||||
|
||||
### 3.5 Expressions (Partial)
|
||||
|
||||
```
|
||||
Expr ::= Literal
|
||||
| Identifier
|
||||
| CallExpr
|
||||
| Block
|
||||
| IfExpr
|
||||
| WhenExpr
|
||||
| ForExpr
|
||||
| ReturnExpr
|
||||
```
|
||||
|
||||
Expression grammar is intentionally restricted in v0.
|
||||
|
||||
---
|
||||
|
||||
## 4. Canonical AST
|
||||
|
||||
The frontend **must** produce a canonical AST.
|
||||
|
||||
### 4.1 AST Invariants
|
||||
|
||||
* AST nodes are immutable after creation
|
||||
* Parent pointers are optional
|
||||
* Source spans must be preserved for diagnostics
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Core Node Kinds
|
||||
|
||||
Minimal required node kinds:
|
||||
|
||||
* `FileNode`
|
||||
* `ImportNode`
|
||||
* `ServiceNode`
|
||||
* `FunctionNode`
|
||||
* `StructDeclNode`
|
||||
* `ContractDeclNode`
|
||||
* `BlockNode`
|
||||
* `LetNode`
|
||||
* `CallNode`
|
||||
* `IfNode`
|
||||
* `WhenNode`
|
||||
* `ForNode`
|
||||
* `ReturnNode`
|
||||
|
||||
Implementers may add internal nodes but must normalize before later phases.
|
||||
|
||||
---
|
||||
|
||||
## 5. Symbol Collection Phase
|
||||
|
||||
### 5.1 Purpose
|
||||
|
||||
Symbol Collection builds **module‑level symbol tables** without resolving bodies.
|
||||
|
||||
Collected symbols:
|
||||
|
||||
* `pub` and `mod` type declarations
|
||||
* `pub` and `mod` services
|
||||
|
||||
Excluded:
|
||||
|
||||
* function bodies
|
||||
* expressions
|
||||
* local bindings
|
||||
|
||||
---
|
||||
|
||||
### 5.2 Namespaces
|
||||
|
||||
PBS has **two namespaces**:
|
||||
|
||||
* Type namespace
|
||||
* Value namespace
|
||||
|
||||
Rules:
|
||||
|
||||
* A name may not exist in both namespaces
|
||||
* Violations are compile‑time errors
|
||||
|
||||
---
|
||||
|
||||
## 6. Resolver Phase
|
||||
|
||||
### 6.1 Responsibilities
|
||||
|
||||
Resolver must:
|
||||
|
||||
* resolve all identifiers
|
||||
* enforce visibility rules
|
||||
* bind references to symbols
|
||||
|
||||
Resolution order (per namespace):
|
||||
|
||||
1. local bindings
|
||||
2. file‑private declarations
|
||||
3. module symbols
|
||||
4. imported symbols
|
||||
|
||||
---
|
||||
|
||||
### 6.2 Visibility Rules (Normative)
|
||||
|
||||
* file‑private: visible only in the same file
|
||||
* `mod`: visible within the module
|
||||
* `pub`: visible across modules via import
|
||||
|
||||
Violations are errors.
|
||||
|
||||
---
|
||||
|
||||
## 7. Type Checking
|
||||
|
||||
### 7.1 Type Categories
|
||||
|
||||
Frontend must support:
|
||||
|
||||
* primitive types
|
||||
* struct value types
|
||||
* `optional<T>`
|
||||
* `result<T, E>`
|
||||
* gate‑backed types (opaque at frontend level)
|
||||
|
||||
---
|
||||
|
||||
### 7.2 Mutability Rules
|
||||
|
||||
* mutability belongs to bindings, not types
|
||||
* `mut` is part of binding metadata
|
||||
* mutability violations are compile‑time errors
|
||||
|
||||
---
|
||||
|
||||
### 7.3 Function Checking
|
||||
|
||||
Rules:
|
||||
|
||||
* all paths must return a value unless `else` fallback exists
|
||||
* `optional<T>` may implicitly return `none`
|
||||
* `result<T,E>` must return explicitly
|
||||
|
||||
---
|
||||
|
||||
## 8. Desugaring and Lowering
|
||||
|
||||
### 8.1 Purpose
|
||||
|
||||
Lowering transforms surface syntax into a minimal core language.
|
||||
|
||||
Examples:
|
||||
|
||||
* `take x.push(v)` → `mutate x as t { t.push(v) }`
|
||||
* `when` → conditional expression node
|
||||
* implicit `return none` for `optional<T>`
|
||||
|
||||
Lowered AST must contain **no syntactic sugar**.
|
||||
|
||||
---
|
||||
|
||||
## 9. Diagnostics Model
|
||||
|
||||
Diagnostics are first‑class frontend outputs.
|
||||
|
||||
### 9.1 Categories
|
||||
|
||||
* Error — compilation must fail
|
||||
* Warning — compilation may continue
|
||||
|
||||
---
|
||||
|
||||
### 9.2 Required Errors
|
||||
|
||||
Examples:
|
||||
|
||||
* unresolved identifier
|
||||
* visibility violation
|
||||
* type mismatch
|
||||
* mutability violation
|
||||
* invalid gate conversion
|
||||
|
||||
---
|
||||
|
||||
## 10. Runtime Interface Assumptions
|
||||
|
||||
Frontend assumes:
|
||||
|
||||
* host‑bound contracts map to runtime syscalls
|
||||
* allocation primitives exist (`alloc`)
|
||||
* reference counting is handled by runtime
|
||||
|
||||
Frontend must **not** assume GC or heap layout.
|
||||
|
||||
---
|
||||
|
||||
## 11. Determinism Guarantees
|
||||
|
||||
A valid PBS frontend **must guarantee**:
|
||||
|
||||
* deterministic parsing
|
||||
* deterministic name resolution
|
||||
* deterministic type checking
|
||||
* deterministic diagnostics
|
||||
|
||||
No frontend stage may depend on execution order or host state.
|
||||
|
||||
---
|
||||
|
||||
## 12. Conformance Criteria
|
||||
|
||||
A frontend is PBS‑v0‑conformant if:
|
||||
|
||||
* it implements all rules in this document
|
||||
* it produces canonical ASTs
|
||||
* it rejects all invalid programs defined herein
|
||||
|
||||
This document is the **source of truth** for PBS v0 frontend behavior.
|
||||
|
||||
---
|
||||
|
||||
## 13. Future Evolution (Non‑Normative)
|
||||
|
||||
Future versions may add:
|
||||
|
||||
* pattern matching
|
||||
* richer type inference
|
||||
* macros
|
||||
|
||||
No v0 frontend is required to support these.
|
||||
|
||||
---
|
||||
|
||||
## End of Spec
|
||||
@@ -0,0 +1,341 @@
|
||||
# Prometeu Base Script (PBS)
|
||||
|
||||
> **A didactic scripting language for game development with explicit cost, explicit memory, and predictable runtime.**
|
||||
|
||||
---
|
||||
|
||||
## 0. What PBS Is (and What It Is Not)
|
||||
|
||||
PBS (Prometeu Base Script) is a **small, explicit scripting language designed for game engines and real‑time runtimes**.
|
||||
|
||||
Its core goals are:
|
||||
|
||||
* **Didactic clarity** — the language teaches how memory, data, and APIs really work.
|
||||
* **Game‑friendly execution** — predictable runtime, no hidden allocation, no tracing GC.
|
||||
* **Explicit cost model** — you always know *when* you allocate, *where* data lives, and *who* can mutate it.
|
||||
|
||||
PBS is **not**:
|
||||
|
||||
* a general‑purpose application language
|
||||
* a productivity scripting language like Python or Lua
|
||||
* a language that hides runtime cost
|
||||
|
||||
PBS is intentionally opinionated. It is built for developers who want **control, predictability, and understanding**, especially in **game and engine contexts**.
|
||||
|
||||
---
|
||||
|
||||
## 1. The Core Philosophy
|
||||
|
||||
PBS is built around one rule:
|
||||
|
||||
> **If you do not allocate, you are safe. If you allocate, you are responsible.**
|
||||
|
||||
From this rule, everything else follows.
|
||||
|
||||
### 1.1 Two Worlds
|
||||
|
||||
PBS has **two explicit memory worlds**:
|
||||
|
||||
| World | Purpose | Properties |
|
||||
| ----- | -------------- | ---------------------------------------------- |
|
||||
| SAFE | Stack / values | No aliasing, no leaks, no shared mutation |
|
||||
| HIP | Storage / heap | Explicit aliasing, shared mutation, refcounted |
|
||||
|
||||
You never cross between these worlds implicitly.
|
||||
|
||||
---
|
||||
|
||||
## 2. First Contact: SAFE‑Only PBS
|
||||
|
||||
A PBS program that never allocates lives entirely in the SAFE world.
|
||||
|
||||
SAFE code:
|
||||
|
||||
* uses value semantics
|
||||
* copies data on assignment (conceptually)
|
||||
* cannot leak memory
|
||||
* cannot accidentally share mutable state
|
||||
|
||||
This makes SAFE PBS ideal for:
|
||||
|
||||
* gameplay logic
|
||||
* math and simulation
|
||||
* AI logic
|
||||
* scripting without fear
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
let a = Vector(1, 2);
|
||||
let b = a; // conceptual copy
|
||||
|
||||
b.scale(2);
|
||||
// a is unchanged
|
||||
```
|
||||
|
||||
No pointers. No references. No surprises.
|
||||
|
||||
---
|
||||
|
||||
## 3. Values, Not Objects
|
||||
|
||||
PBS does not have objects with identity by default.
|
||||
|
||||
### 3.1 Value Types
|
||||
|
||||
All basic types are **values**:
|
||||
|
||||
* numbers
|
||||
* bool
|
||||
* string (immutable)
|
||||
* tuples
|
||||
* user‑defined `struct`
|
||||
|
||||
A value:
|
||||
|
||||
* has no identity
|
||||
* has no lifetime beyond its scope
|
||||
* is safe to copy
|
||||
|
||||
This matches how most gameplay data *should* behave.
|
||||
|
||||
---
|
||||
|
||||
## 4. Structs (Data First)
|
||||
|
||||
Structs are **pure data models**.
|
||||
|
||||
```pbs
|
||||
declare struct Vector(x: float, y: float)
|
||||
{
|
||||
pub fn len(self: this): float { ... }
|
||||
pub fn scale(self: mut this, s: float): void { ... }
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
* fields are private
|
||||
* mutation is explicit (`mut this`)
|
||||
* no inheritance
|
||||
* no identity
|
||||
|
||||
Structs are designed to be:
|
||||
|
||||
* cache‑friendly
|
||||
* predictable
|
||||
* easy to reason about
|
||||
|
||||
---
|
||||
|
||||
## 5. Mutability Is a Property of Bindings
|
||||
|
||||
In PBS, **types are never mutable**. Bindings are.
|
||||
|
||||
```pbs
|
||||
let v = Vector.ZERO;
|
||||
v.scale(); // ERROR
|
||||
|
||||
let w = mut Vector.ZERO;
|
||||
w.scale(); // OK
|
||||
```
|
||||
|
||||
This single rule eliminates entire classes of bugs.
|
||||
|
||||
---
|
||||
|
||||
## 6. When You Need Power: Allocation (HIP World)
|
||||
|
||||
Allocation is **explicit**.
|
||||
|
||||
```pbs
|
||||
let enemies = alloc list<Enemy>();
|
||||
```
|
||||
|
||||
Once you allocate:
|
||||
|
||||
* data lives in Storage (heap)
|
||||
* access happens through **gates** (handles)
|
||||
* aliasing is real and visible
|
||||
|
||||
This is intentional and explicit.
|
||||
|
||||
---
|
||||
|
||||
## 7. Gates (Handles, Not Pointers)
|
||||
|
||||
A gate is a small value that refers to heap storage.
|
||||
|
||||
Properties:
|
||||
|
||||
* cheap to copy
|
||||
* may alias shared data
|
||||
* managed by reference counting
|
||||
|
||||
### 7.1 Strong vs Weak Gates
|
||||
|
||||
* **Strong gate** — keeps data alive
|
||||
* **Weak gate** — observes without ownership
|
||||
|
||||
```pbs
|
||||
let a = alloc Node;
|
||||
let w: weak<Node> = a as weak;
|
||||
let maybeA = w as strong;
|
||||
```
|
||||
|
||||
This model mirrors real engine constraints without hiding them.
|
||||
|
||||
---
|
||||
|
||||
## 8. Controlled Access to Storage
|
||||
|
||||
Heap data is never accessed directly.
|
||||
|
||||
You must choose *how*:
|
||||
|
||||
* `peek` — copy to SAFE
|
||||
* `borrow` — temporary read‑only access
|
||||
* `mutate` — temporary mutable access
|
||||
|
||||
```pbs
|
||||
mutate enemies as e
|
||||
{
|
||||
e.push(newEnemy);
|
||||
}
|
||||
```
|
||||
|
||||
This keeps mutation visible and scoped.
|
||||
|
||||
---
|
||||
|
||||
## 9. Errors Are Values
|
||||
|
||||
PBS has no exceptions.
|
||||
|
||||
### 9.1 `optional<T>`
|
||||
|
||||
Used when absence is normal.
|
||||
|
||||
```pbs
|
||||
let x = maybeValue else 0;
|
||||
```
|
||||
|
||||
### 9.2 `result<T, E>`
|
||||
|
||||
Used when failure matters.
|
||||
|
||||
```pbs
|
||||
let v = loadTexture(path)?;
|
||||
```
|
||||
|
||||
Error propagation is explicit and typed.
|
||||
|
||||
---
|
||||
|
||||
## 10. Control Flow Without Surprises
|
||||
|
||||
PBS favors explicit flow:
|
||||
|
||||
* `if` — control only
|
||||
* `when` — expression
|
||||
* `for` — bounded loops only
|
||||
|
||||
```pbs
|
||||
for i in [0b..count] {
|
||||
update(i);
|
||||
}
|
||||
```
|
||||
|
||||
No unbounded iteration by accident.
|
||||
|
||||
---
|
||||
|
||||
## 11. Services: Explicit API Boundaries
|
||||
|
||||
A `service` is how behavior crosses module boundaries.
|
||||
|
||||
```pbs
|
||||
pub service Audio
|
||||
{
|
||||
fn play(sound: Sound): void;
|
||||
}
|
||||
```
|
||||
|
||||
Services are:
|
||||
|
||||
* explicit
|
||||
* statically checked
|
||||
* singleton‑like
|
||||
|
||||
They map naturally to engine subsystems.
|
||||
|
||||
---
|
||||
|
||||
## 12. Contracts: Static Guarantees
|
||||
|
||||
Contracts define **what exists**, not how.
|
||||
|
||||
```pbs
|
||||
pub declare contract Gfx host
|
||||
{
|
||||
fn drawText(x: int, y: int, msg: string): void;
|
||||
}
|
||||
```
|
||||
|
||||
Contracts:
|
||||
|
||||
* have no runtime cost
|
||||
* are validated at compile time
|
||||
* define engine ↔ script boundaries
|
||||
|
||||
---
|
||||
|
||||
## 13. Modules (Simple and Predictable)
|
||||
|
||||
* one directory = one module
|
||||
* only `pub` symbols cross modules
|
||||
* no side effects on import
|
||||
|
||||
This keeps build and runtime deterministic.
|
||||
|
||||
---
|
||||
|
||||
## 14. Why PBS Works for Games
|
||||
|
||||
PBS is designed around real engine needs:
|
||||
|
||||
* frame‑based execution
|
||||
* explicit allocation
|
||||
* deterministic cleanup
|
||||
* predictable performance
|
||||
|
||||
It teaches developers **why engines are written the way they are**, instead of hiding reality.
|
||||
|
||||
---
|
||||
|
||||
## 15. Who PBS Is For
|
||||
|
||||
PBS is for:
|
||||
|
||||
* game developers who want control
|
||||
* engine developers
|
||||
* students learning systems concepts
|
||||
* educators teaching memory and runtime models
|
||||
|
||||
PBS is *not* for:
|
||||
|
||||
* rapid prototyping without constraints
|
||||
* general app scripting
|
||||
* hiding complexity
|
||||
|
||||
---
|
||||
|
||||
## 16. Design Promise
|
||||
|
||||
PBS makes one promise:
|
||||
|
||||
> **Nothing happens behind your back.**
|
||||
|
||||
If you understand PBS, you understand your runtime.
|
||||
|
||||
That is the product.
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user