Prexonite, a .NET hosted scripting language with a focus on meta-programming and embedded DSLs
CLAUDE.md
Christian Klauser
(Nov 15, 2025, 11:48 AM +0100)
c3f1b83b
02213712
+163
+163
CLAUDE.md
+163
CLAUDE.md
···
1
+
# Project Overview
2
+
3
+
Prexonite Script is a dynamically-typed, embeddable .NET scripting language focused on meta-programming and DSL construction.
4
+
It features compile-time macros, optional JIT compilation to CIL, and rich interop with .NET objects.
5
+
6
+
# Build & Test Commands
7
+
8
+
```bash
9
+
# Build entire solution
10
+
dotnet build
11
+
12
+
# Run all tests (NUnit + .pxs integration tests)
13
+
dotnet test
14
+
15
+
# Run CLI interpreter
16
+
dotnet run --project Prx
17
+
18
+
# Run specific test
19
+
dotnet test --filter "FullyQualifiedName~TestName"
20
+
```
21
+
22
+
# Solution Structure
23
+
24
+
- **Prexonite**: Core language library (VM, compiler, type system, standard library)
25
+
- **PrexoniteTests**: NUnit test suite with .pxs integration tests
26
+
- **Prx**: Command-line REPL and script runner
27
+
- **PxCoco**: Modified Coco/R parser generator (build-time tool)
28
+
29
+
# High-Level Architecture
30
+
31
+
## Compilation Pipeline
32
+
33
+
1. **Lexical Analysis** (`Compiler/Lexer.cs`) - Generated from `Prexonite.lex` via CSFlex
34
+
2. **Parsing** (`Compiler/Parser.cs`) - Generated from merged `.atg` grammar fragments via PxCoco
35
+
3. **AST Construction** (`Compiler/AST/`) - 50+ node types representing language constructs
36
+
4. **Macro Expansion** (`Compiler/Macro/`) - Compile-time AST transformation (macros run during compilation)
37
+
5. **Symbol Resolution** (`Compiler/Symbolic/`) - Namespace imports and qualified name resolution
38
+
6. **Bytecode Generation** (`Compiler/CompilerTarget.cs`) - AST nodes emit stack-based instructions
39
+
7. **Optional CIL Compilation** (`Compiler/Cil/`) - JIT compilation to native .NET methods via Reflection.Emit
40
+
41
+
## Execution Model
42
+
43
+
**Stack-based Virtual Machine** with context switching:
44
+
45
+
- **Engine** (`Engine.cs`): Global component managing type registry, commands, and call stack
46
+
- **StackContext** hierarchy: Abstract execution context (stack frames) with implementations:
47
+
- `FunctionContext`: Interpreted bytecode execution
48
+
- `CilFunctionContext`: JIT-compiled native execution
49
+
- `CoroutineContext`, `CooperativeContext`: Concurrency support
50
+
- **Instruction Set** (`Instruction.cs`): Stack-based opcodes (load, store, call, jump, operators)
51
+
- **PValue** (`PValue.cs`): Universal value container `(object Value, PType Type)` with dynamic dispatch
52
+
53
+
## Type System
54
+
55
+
All operations dispatch through **PType** hierarchy:
56
+
- Primitive types: `IntPType`, `RealPType`, `BoolPType`, `StringPType`, etc.
57
+
- Collection types: `ListPType`, `HashPType`, `StructurePType`
58
+
- CLR interop: `ObjectPType` wraps .NET objects
59
+
- All operators use runtime dispatch (no static optimization)
60
+
61
+
## Module System
62
+
63
+
- **Module** (`Modular/Module.cs`): Container for functions, variables, metadata
64
+
- **Application** (`Application.cs`): Runtime instance of a module with initialization
65
+
- **Build System** (`Compiler/Build/`):
66
+
- `SelfAssemblingPlan`: Automatic dependency resolution
67
+
- Standard library auto-included: `prx.prim`, `prx.core`, `sys`, `prx.v2.prelude`
68
+
69
+
## Commands (Built-in Functions)
70
+
71
+
Implemented as .NET types in `Commands/`:
72
+
- **Core**: Basic operations, type conversions (`Commands/Core/`)
73
+
- **List**: Functional programming (`map`, `filter`, `foldl`, `where`, etc.)
74
+
- **Concurrency**: Channels, async operations (`Commands/Concurrency/`)
75
+
- **Math/Text**: Domain-specific utilities
76
+
77
+
Interface: `PValue Run(StackContext sctx, PValue[] args)`
78
+
79
+
# Important Conventions
80
+
81
+
## Naming
82
+
- PTypes: `*PType` suffix (e.g., `IntPType`)
83
+
- AST nodes: `Ast*` prefix (e.g., `AstBlock`)
84
+
- Internal helpers: Leading underscore (e.g., `_emitCode()`)
85
+
- Meta keys: Backslash prefix for system keys (e.g., `\init`, `\sharedNames`)
86
+
87
+
## String Comparison
88
+
**Case-insensitive throughout** - use `Engine.StringsAreEqual()` or `StringComparer.OrdinalIgnoreCase`
89
+
90
+
## Code Organization
91
+
- Namespaces mirror directory structure
92
+
- Compiler components: `Prexonite.Compiler.*`
93
+
- Runtime components: directly under `Prexonite`
94
+
95
+
# Standard Library Structure
96
+
97
+
Embedded scripts in `prxlib/`:
98
+
- **prx.prim**: Primitive operations (direct command exports)
99
+
- **prx.core**: Core namespace with submodules:
100
+
- `prx.core.seq`: Sequence operations
101
+
- `prx.core.nonstrict`: Lazy evaluation
102
+
- `prx.core.text`, `prx.core.math`: Domain utilities
103
+
- **prx.v2.prelude**: Default prelude (auto-imported in v2 mode)
104
+
105
+
# Testing Infrastructure
106
+
107
+
- **C# Unit Tests**: `PrexoniteTests/Tests/` - NUnit tests for compiler, VM, types
108
+
- **Integration Tests**: `PrexoniteTests/psr-tests/*.test.pxs` - Prexonite script test suites
109
+
- **Test Runner**: `run_tests.pxs` orchestrates .pxs test execution
110
+
111
+
# Performance Considerations
112
+
113
+
1. **JIT Compilation**: Optional CIL compilation via `Compiler/Cil/` for hot code paths
114
+
2. **Overload Resolution**: Happens at every call site (by design, performance impact)
115
+
3. **Caching**: Function/command reference caching available (opt-in)
116
+
4. **Ready-to-Run**: CLI uses R2R compilation in release mode
117
+
118
+
# Build-Time Code Generation
119
+
120
+
- **Grammar Assembly**: `.atg` fragments merged via MSBuild into `Prexonite__gen.atg`
121
+
- **Parser Generation**: PxCoco generates `Parser.cs` from grammar
122
+
- **Lexer Generation**: CSFlex generates `Lexer.cs` from `Prexonite.lex`
123
+
- **T4 Templates**: Some code generation via TextTemplatingFileGenerator
124
+
125
+
# Meta-Programming Features
126
+
127
+
## Macros
128
+
- Execute at compile-time with full AST access via `MacroContext`
129
+
- Can generate arbitrary AST nodes or crash the compiler (unsafe by design)
130
+
- Built-in macros in `Compiler/Macro/Commands/`: `call\macro`, `pack`, `unpack`, partial application
131
+
132
+
## Compile-Time Evaluation
133
+
- Interpreter runs during compilation for constant folding and code generation
134
+
- See `Commands/CompileTimeValue.cs`
135
+
136
+
# Quick Orientation Checklist
137
+
138
+
1. **VM execution entry point**: `Engine.Process()` in `VM.cs`
139
+
2. **Instruction set**: `OpCode` enum in `Instruction.cs`
140
+
3. **AST structure**: `Compiler/AST/AstNode.cs` base class
141
+
4. **Type system core**: `PValue.cs` and `Types/PType.cs`
142
+
5. **Compilation flow**: `Loader.cs` → `CompilerTarget.cs` → `AstNode.DoEmitCode()`
143
+
144
+
# Common Development Tasks
145
+
146
+
## Add Built-in Function
147
+
1. Create `PCommand` implementation in `Commands/`
148
+
2. Register in `Engine.cs` constructor or via meta-programming
149
+
150
+
## Add AST Node
151
+
1. Inherit from `AstNode` in `Compiler/AST/`
152
+
2. Implement `DoEmitCode(CompilerTarget target)` to emit bytecode
153
+
3. Extend `Prexonite/Compiler/AST/AstFactoryBase.cs`
154
+
4. Update parser if adding new syntax
155
+
156
+
## Add OpCode
157
+
1. Add to `OpCode` enum in `Instruction.cs`
158
+
2. Implement execution in `FunctionContext.Run()` switch statement
159
+
3. Add CIL generation in `Compiler/Cil/` if needed
160
+
161
+
## Modify Grammar
162
+
1. Edit `.atg` fragments in `Compiler/Grammar/`
163
+
2. Rebuild to regenerate parser via PxCoco