Status: Lexer-Derived Specification
Last Updated: January 8, 2026
Welcome to the Blend65 language specification. This documentation describes the complete syntax, semantics, and features of the Blend65 programming language—a modern language designed to compile to 6502-family systems (C64, VIC-20, Commander X16, and more).
Blend65 provides structured programming, modularity, and a practical type system while still enabling fine-grained memory placement and low-level control for 6502 systems. This specification is lexer-derived, meaning it strictly describes what the language frontend can tokenize and parse today.
| Document | Description |
|---|---|
| 00-overview.md | Language introduction, design goals, and specification status |
| 01-lexical-structure.md | Character sets, tokens, identifiers, keywords, literals, comments |
| 02-grammar.md | EBNF grammar overview and common building blocks |
| 03-program-structure.md | Program structure and top-level ordering rules |
| 04-module-system.md | Module declarations, qualified names, import/export system |
| 05-type-system.md | Primitive types, type aliases, enums |
| 06-expressions-statements.md | Expressions, operators, statements, control flow |
| Document | Description |
|---|---|
| 10-variables.md | Variable declarations, storage classes, mutability |
| 11-functions.md | Function declarations, parameters, return statements, callbacks |
| 12-memory-mapped.md | Memory-mapped variables (@map) - all 4 forms |
| 13-6502-features.md | 6502-specific features and guidelines |
| Document | Description |
|---|---|
| 20-error-handling.md | Lexer-level errors and diagnostics |
| 21-examples.md | Complete working code examples |
| 30-compiler-design.md | Compiler design decisions and rationale |
New to Blend65? Start with:
- Overview - Understand the language philosophy
- Lexical Structure - Learn basic syntax
- Program Structure - Understand how programs are organized
- Examples - See complete working code
Looking for specific features?
- Variables and memory placement → Variables
- Hardware register access → Memory-Mapped
- Functions and callbacks → Functions
- Control flow (if/while/for) → Expressions & Statements
This specification is derived from the current lexer and parser implementation:
- Lexer:
packages/compiler/src/lexer/ - Parser:
packages/compiler/src/parser/ - Tests:
packages/compiler/src/__tests__/
If a construct is not tokenizable/parseable by the frontend, it is not specified here.
When adding new language features:
- Update the relevant specification document(s)
- Add cross-references where needed
- Include complete examples
- Update this README if adding new documents
Throughout this specification:
- EBNF grammar is used to express syntax rules
- Code examples show typical usage patterns
- ✅/❌ markers indicate correct vs. incorrect syntax
- Cross-references link to related sections in other documents