added first steps on pbs pipeline
This commit is contained in:
@@ -0,0 +1,373 @@
|
||||
# PBS - Language Syntax Specification v0
|
||||
|
||||
Status: Draft (Normative for FE rewrite)
|
||||
Scope: PBS v0 Core syntax (lexer + parser contract)
|
||||
Language: English only
|
||||
|
||||
## 1. Goals
|
||||
|
||||
This document defines the canonical PBS v0 Core syntax.
|
||||
|
||||
It is designed to:
|
||||
|
||||
- be deterministic to parse,
|
||||
- be stable for tests and tooling,
|
||||
- align with runtime authority,
|
||||
- provide a clear baseline for frontend rewrite.
|
||||
|
||||
This document defines syntax only. Runtime behavior, bytecode encoding, scheduling, and GC internals are out of scope.
|
||||
|
||||
## 2. Authority and precedence
|
||||
|
||||
Normative precedence order:
|
||||
|
||||
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
||||
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
||||
3. This syntax specification
|
||||
4. Legacy references (`docs/specs/pbs_old/*`)
|
||||
|
||||
If a syntax rule from legacy material conflicts with runtime or bytecode authority, that rule is invalid.
|
||||
|
||||
## 3. Source model
|
||||
|
||||
- Source encoding: UTF-8.
|
||||
- Line terminators: `\n` and `\r\n` are both valid.
|
||||
- Whitespace is insignificant except as separator.
|
||||
- A source file is a declaration unit; top-level executable statements are forbidden.
|
||||
|
||||
## 4. Lexical specification
|
||||
|
||||
### 4.1 Tokens
|
||||
|
||||
The lexer must produce at least:
|
||||
|
||||
- identifiers,
|
||||
- keywords,
|
||||
- numeric literals,
|
||||
- string literals,
|
||||
- punctuation,
|
||||
- operators,
|
||||
- comments,
|
||||
- EOF.
|
||||
|
||||
Each token must carry a source span (byte offsets).
|
||||
|
||||
### 4.2 Comments
|
||||
|
||||
- Line comment: `// ...` until line end.
|
||||
- Block comments are not part of v0 Core.
|
||||
|
||||
### 4.3 Identifiers
|
||||
|
||||
Identifier:
|
||||
|
||||
- starts with `_` or alphabetic character,
|
||||
- continues with `_`, alphabetic, or digit characters.
|
||||
|
||||
Keywords cannot be used as identifiers.
|
||||
|
||||
### 4.4 Keywords
|
||||
|
||||
Active keywords in `.pbs` files (v0 Core):
|
||||
|
||||
- `import`, `from`, `as`
|
||||
- `service`, `fn`
|
||||
- `declare`, `struct`, `contract`, `error`
|
||||
- `let`, `mut`
|
||||
- `if`, `else`, `when`, `for`, `in`, `return`
|
||||
- `true`, `false`
|
||||
|
||||
Barrel-only keywords:
|
||||
|
||||
- `pub`, `mod`
|
||||
- `type`
|
||||
|
||||
Reserved (not active in `.pbs` v0 Core grammar, but reserved):
|
||||
|
||||
- `host`, `handle`
|
||||
- `alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`
|
||||
- `spawn`, `yield`, `sleep`
|
||||
|
||||
### 4.5 Literals
|
||||
|
||||
Numeric literals:
|
||||
|
||||
- `IntLit`: decimal integer (`0`, `42`, `1000`)
|
||||
- `FloatLit`: decimal float with dot (`3.14`, `0.5`)
|
||||
- `BoundedLit`: decimal integer with `b` suffix (`0b`, `255b`)
|
||||
|
||||
String literals:
|
||||
|
||||
- delimited by `"`.
|
||||
- support escapes: `\\`, `\"`, `\n`, `\r`, `\t`.
|
||||
|
||||
Booleans:
|
||||
|
||||
- `true`, `false`.
|
||||
|
||||
## 5. Module and barrel model
|
||||
|
||||
### 5.1 Required files
|
||||
|
||||
A module is valid only if it contains:
|
||||
|
||||
- one or more `.pbs` source files,
|
||||
- exactly one `mod.barrel` file.
|
||||
|
||||
Missing `mod.barrel` is a compile-time error.
|
||||
|
||||
### 5.2 Barrel responsibility
|
||||
|
||||
`mod.barrel` is the only place where module visibility is defined.
|
||||
|
||||
Visibility levels:
|
||||
|
||||
- `mod`: visible across files in the same module.
|
||||
- `pub`: visible to other modules through imports.
|
||||
|
||||
Any top-level declaration not listed in `mod.barrel` is file-private.
|
||||
Using `mod` or `pub` as top-level declaration modifiers in `.pbs` files is a syntax error.
|
||||
|
||||
### 5.3 Barrel grammar
|
||||
|
||||
```ebnf
|
||||
BarrelFile ::= BarrelItem* EOF
|
||||
BarrelItem ::= BarrelVisibility BarrelKind Identifier ';'
|
||||
BarrelVisibility ::= 'mod' | 'pub'
|
||||
BarrelKind ::= 'fn' | 'type' | 'service'
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `mod.barrel` cannot declare aliases.
|
||||
- Barrel item order has no semantic meaning.
|
||||
- The same symbol cannot appear more than once in `mod.barrel`.
|
||||
- Each barrel item must resolve to an existing top-level declaration in the module.
|
||||
- Alias syntax is allowed only in `import` declarations.
|
||||
- Importing modules may only import symbols marked as `pub` in the target module barrel.
|
||||
|
||||
Examples:
|
||||
|
||||
```barrel
|
||||
mod fn clamp;
|
||||
pub fn sum;
|
||||
pub type Vector;
|
||||
mod service Audio;
|
||||
```
|
||||
|
||||
## 6. File and declaration grammar
|
||||
|
||||
EBNF conventions used:
|
||||
|
||||
- `A?` optional
|
||||
- `A*` zero or more
|
||||
- `A+` one or more
|
||||
- terminals in single quotes
|
||||
|
||||
### 6.1 File
|
||||
|
||||
```ebnf
|
||||
File ::= ImportDecl* TopDecl* EOF
|
||||
```
|
||||
|
||||
### 6.2 Imports
|
||||
|
||||
Imports must target modules, never files.
|
||||
|
||||
```ebnf
|
||||
ImportDecl ::= 'import' ( ModuleRef | '{' ImportList '}' 'from' ModuleRef ) ';'
|
||||
ImportList ::= ImportItem (',' ImportItem)*
|
||||
ImportItem ::= Identifier ('as' Identifier)?
|
||||
ModuleRef ::= '@' Identifier ':' ModulePath
|
||||
ModulePath ::= Identifier ('/' Identifier)*
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```pbs
|
||||
import @core:math;
|
||||
import { Vector, Matrix as Mat } from @core:math;
|
||||
```
|
||||
|
||||
### 6.3 Top-level declarations
|
||||
|
||||
```ebnf
|
||||
TopDecl ::= TypeDecl | ServiceDecl | FunctionDecl
|
||||
```
|
||||
|
||||
Top-level `let` and top-level statements are not allowed.
|
||||
|
||||
### 6.4 Type declarations
|
||||
|
||||
```ebnf
|
||||
TypeDecl ::= 'declare' TypeKind Identifier TypeBody
|
||||
TypeKind ::= 'struct' | 'contract' | 'error'
|
||||
TypeBody ::= '{' TypeMember* '}'
|
||||
TypeMember ::= FieldDecl | FnSigDecl
|
||||
FieldDecl ::= Identifier ':' TypeRef ';'
|
||||
FnSigDecl ::= 'fn' Identifier ParamList ReturnType? ';'
|
||||
```
|
||||
|
||||
### 6.5 Services
|
||||
|
||||
```ebnf
|
||||
ServiceDecl ::= 'service' Identifier (':' Identifier)? ServiceBody
|
||||
ServiceBody ::= '{' ServiceMember* '}'
|
||||
ServiceMember ::= 'fn' Identifier ParamList ReturnType? Block
|
||||
```
|
||||
|
||||
### 6.6 Functions
|
||||
|
||||
```ebnf
|
||||
FunctionDecl ::= 'fn' Identifier ParamList ReturnType? ElseFallback? Block
|
||||
ParamList ::= '(' Param (',' Param)* ')'
|
||||
Param ::= 'mut'? Identifier ':' TypeRef
|
||||
ReturnType ::= ':' TypeRef
|
||||
ElseFallback ::= 'else' Expr
|
||||
```
|
||||
|
||||
## 7. Type syntax
|
||||
|
||||
```ebnf
|
||||
TypeRef ::= TypePrimary
|
||||
TypePrimary ::= SimpleType | GenericType | TupleType
|
||||
SimpleType ::= Identifier
|
||||
GenericType ::= Identifier '<' TypeRef (',' TypeRef)* '>'
|
||||
TupleType ::= '(' TypeRef ',' TypeRef (',' TypeRef){0,4} ')'
|
||||
```
|
||||
|
||||
Runtime alignment:
|
||||
|
||||
- Tuple type arity in v0 Core is 2..6.
|
||||
- This aligns with runtime multi-return slot limits.
|
||||
|
||||
## 8. Statements and blocks
|
||||
|
||||
```ebnf
|
||||
Block ::= '{' Stmt* TailExpr? '}'
|
||||
Stmt ::= LetStmt | ReturnStmt | IfStmt | ForStmt | ExprStmt
|
||||
TailExpr ::= Expr
|
||||
|
||||
LetStmt ::= 'let' 'mut'? Identifier (':' TypeRef)? '=' Expr ';'
|
||||
ReturnStmt ::= 'return' Expr? ';'
|
||||
ExprStmt ::= Expr ';'
|
||||
|
||||
IfStmt ::= 'if' Expr Block ('else' (IfStmt | Block))?
|
||||
ForStmt ::= 'for' Identifier 'in' RangeExpr Block
|
||||
RangeExpr ::= '[' Expr? '..' Expr? ']'
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `if` is a statement in v0 Core.
|
||||
- `when` is an expression.
|
||||
- `break` and `continue` are deferred from v0 Core syntax.
|
||||
|
||||
## 9. Expression grammar and precedence
|
||||
|
||||
Assignment is not an expression in v0 Core.
|
||||
|
||||
```ebnf
|
||||
Expr ::= WhenExpr
|
||||
|
||||
WhenExpr ::= 'when' OrExpr 'then' Expr 'else' Expr | OrExpr
|
||||
|
||||
OrExpr ::= AndExpr ('||' AndExpr)*
|
||||
AndExpr ::= EqualityExpr ('&&' EqualityExpr)*
|
||||
|
||||
EqualityExpr ::= CompareExpr (('==' | '!=') CompareExpr)?
|
||||
CompareExpr ::= CastExpr (('<' | '<=' | '>' | '>=') CastExpr)?
|
||||
|
||||
CastExpr ::= AddExpr ('as' TypeRef)*
|
||||
|
||||
AddExpr ::= MulExpr (('+' | '-') MulExpr)*
|
||||
MulExpr ::= UnaryExpr (('*' | '/' | '%') UnaryExpr)*
|
||||
|
||||
UnaryExpr ::= ('!' | '-') UnaryExpr | CallExpr
|
||||
CallExpr ::= PrimaryExpr ('(' ArgList? ')')*
|
||||
ArgList ::= Expr (',' Expr)*
|
||||
|
||||
Literal ::= IntLit | FloatLit | BoundedLit | StringLit | BoolLit
|
||||
BoolLit ::= 'true' | 'false'
|
||||
PrimaryExpr ::= Literal | Identifier | GroupExpr | Block
|
||||
GroupExpr ::= '(' Expr ')'
|
||||
```
|
||||
|
||||
Non-associative constraints:
|
||||
|
||||
- `a < b < c` is invalid.
|
||||
- `a == b == c` is invalid.
|
||||
|
||||
## 10. Runtime authority alignment constraints
|
||||
|
||||
These are hard constraints for frontend and syntax decisions:
|
||||
|
||||
- Runtime is deterministic and frame-synchronized.
|
||||
- `FRAME_SYNC` is runtime safepoint and not surface syntax.
|
||||
- Heap semantics are GC-based at runtime authority level.
|
||||
- Host interaction is via `SYSCALL` in bytecode and host ABI mapping.
|
||||
- Syscalls are callable but not first-class.
|
||||
|
||||
Syntax implications for v0 Core:
|
||||
|
||||
- No RC/HIP/gate-specific syntax is active.
|
||||
- No closure literal syntax in v0 Core.
|
||||
- No coroutine syntax (`spawn`, `yield`, `sleep`) in v0 Core.
|
||||
|
||||
## 11. Deferred syntax (explicitly out of v0 Core)
|
||||
|
||||
Deferred for later profiles:
|
||||
|
||||
- heap-specialized syntax: `alloc`, `borrow`, `mutate`, `peek`, `take`, `weak`
|
||||
- first-class closure/lambda surface syntax
|
||||
- coroutine surface syntax
|
||||
- pattern matching
|
||||
- macro system
|
||||
|
||||
These words stay reserved so later profiles do not break source compatibility.
|
||||
|
||||
## 12. Conformance requirements for frontend rewrite
|
||||
|
||||
A v0 Core frontend is conformant if:
|
||||
|
||||
- tokenization follows this lexical spec,
|
||||
- barrel parsing and validation follows Section 5,
|
||||
- parsing follows this grammar and precedence,
|
||||
- parser is deterministic,
|
||||
- each token and AST node keeps stable spans,
|
||||
- forbidden constructs produce deterministic diagnostics.
|
||||
|
||||
## 13. Minimal canonical examples
|
||||
|
||||
### 13.1 Function
|
||||
|
||||
```pbs
|
||||
fn sum(a: int, b: int): int {
|
||||
return a + b;
|
||||
}
|
||||
```
|
||||
|
||||
### 13.2 Local function + barrel visibility
|
||||
|
||||
```pbs
|
||||
fn clamp(x: int, lo: int, hi: int): int {
|
||||
if x < lo {
|
||||
return lo;
|
||||
}
|
||||
if x > hi {
|
||||
return hi;
|
||||
}
|
||||
return x;
|
||||
}
|
||||
```
|
||||
|
||||
```barrel
|
||||
mod fn clamp;
|
||||
```
|
||||
|
||||
### 13.3 Imports
|
||||
|
||||
```pbs
|
||||
import @core:math;
|
||||
import { Vec2 as V2 } from @core:math;
|
||||
```
|
||||
@@ -0,0 +1,21 @@
|
||||
# PBS Specifications (Current)
|
||||
|
||||
This directory contains the current PBS specifications for frontend and language work.
|
||||
|
||||
## Authority model
|
||||
|
||||
- Runtime authority: `docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`.
|
||||
- Bytecode authority: `docs/specs/bytecode/ISA_CORE.md`.
|
||||
- Legacy reference only: `docs/specs/pbs_old/*`.
|
||||
|
||||
When a rule conflicts with runtime or bytecode authority, runtime and bytecode authority win.
|
||||
|
||||
## Purpose
|
||||
|
||||
- Define a stable syntax contract for PBS.
|
||||
- Support a full frontend rewrite (lexer, parser, AST, lowering).
|
||||
- Keep grammar deterministic and implementation-friendly.
|
||||
|
||||
## Files
|
||||
|
||||
- `PBS - Language Syntax Specification v0.md`: normative syntax and grammar for PBS v0 Core profile, including mandatory `mod.barrel` visibility rules.
|
||||
Reference in New Issue
Block a user