1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
# Baba Yaga Programming Language
A functional programming language with immutable data structures, pattern matching, and explicit error handling.
## Quick Start
```bash
# Run a program
bun run index.js example.baba
# Or use the compiled binary
./build/baba-yaga-macos-arm64 example.baba
# Interactive REPL
bun run repl.js
# Run tests
bun test
```
## Language Features
- **Immutable by default** - All data structures are immutable
- **Pattern matching** - Powerful `when` expressions with guards for control flow
- **Explicit error handling** - `Result` types with `Ok` and `Err`
- **Currying & partial application** - Functions are curried by default
- **Higher-order functions** - `map`, `filter`, `reduce`, `flatMap`, and more
- **Array programming** - APL/K-inspired operations: `scan`, `at`, `where`, `broadcast`, `zipWith`, `reshape`
- **Function combinators** - `compose`, `pipe`, `apply`, `flip` for functional composition
- **Type annotations** - Optional static typing with runtime validation
- **Rich standard library** - Comprehensive math, string, list, table, validation, and debugging utilities
- **Local bindings** - `with` blocks for staging computations and mutual recursion
## Project Structure
```
baba-yaga/
├── src/
│ ├── core/ # Current optimized implementation
│ ├── legacy/ # Original stable implementation
│ └── benchmarks/ # Performance testing
├── docs/ # Language documentation
├── tests/ # Test suite (226 tests)
├── build/ # Compiled binaries
├── scratch/ # Development files
│ ├── baba/ # Test .baba programs
│ ├── js/ # JavaScript utilities
│ └── docs/ # Technical documentation
├── dev/ # Editor support (VS Code, Vim, etc.)
├── web/ # Web playground
└── experimental/ # Experimental features
```
## Development
### Building Binaries
```bash
# Build for current platform
bun run build
# Build for all platforms
bun run build:all
# Build for specific platform
bun run build:linux
bun run build:windows
bun run build:macos-intel
bun run build:macos-arm
```
### Running Tests
```bash
# All tests
bun test
# Benchmark performance
bun run benchmark
bun run benchmark:full
```
### CLI Options
```bash
bun run index.js program.baba [options]
Options:
--debug Enable debug output
--profile Enable performance profiling
--strict Enable strict mode validation
--legacy Use legacy (stable) engine
```
## Engine Architecture
### Current Status (v2.0.0)
- **Default Engine**: Legacy lexer/parser/interpreter (stable, reliable)
- **Optimized Engine**: Available but **disabled by default** due to [critical lexer bug](scratch/docs/LEXER_BUG_REPORT.md)
- **Performance**: Legacy engine handles all test cases correctly
- **Compatibility**: 226 tests pass, full language support
### Key Components
- **Lexer**: Tokenizes source code (legacy character-by-character parsing)
- **Parser**: Builds Abstract Syntax Tree (recursive descent parser)
- **Interpreter**: Executes AST with scope management and built-in functions
- **Error System**: Rich error messages with source location and suggestions
- **Configuration**: Flexible engine settings and feature flags
## Example Programs
### Basic Syntax
```baba
// Variables and functions
x : 42;
add : a b -> a + b;
result : add 10 5;
// Lists and higher-order functions
numbers : [1, 2, 3, 4, 5];
doubled : map (x -> x * 2) numbers;
sum : reduce (acc x -> acc + x) 0 doubled;
// Array programming operations
evens : where (x -> (x % 2) = 0) numbers; // [1, 3] (indices)
evenValues : at evens numbers; // [2, 4]
cumulative : cumsum numbers; // [0, 1, 3, 6, 10, 15]
matrix : reshape [2, 3] (range 1 6); // [[1,2,3], [4,5,6]]
// Pattern matching with guards
classify : n ->
when n is
0 then "zero"
x if ((x > 0) and (x < 10)) then "small positive"
Int then when (n > 10) is true then "big" _ then "small"
_ then "unknown";
// Error handling
safeDivide : a b ->
when b is
0 then Err "Division by zero"
_ then Ok (a / b);
// Function composition and utilities
processData : xs ->
with (
validated : filter (validate.range 1 100) xs;
grouped : chunk validated 3;
processed : map (chunk -> reduce (acc x -> acc + x) 0 chunk) grouped;
) -> processed;
```
### Conway's Game of Life
See [scratch/baba/life-final.baba](scratch/baba/life-final.baba) for a complete implementation.
## Documentation
- [Language Crash Course](docs/00_crash-course.md) - Complete language guide with all features
- [Functional Programming](docs/01_functional.md) - Higher-order functions, combinators, and array programming
- [Data Structures](docs/02_data-structures.md) - Lists, tables, and comprehensive array operations
- [Pattern Matching](docs/03_pattern-matching.md) - `when` expressions, guards, and advanced patterns
- [Type System](docs/04_types.md) - Optional typing with runtime validation
- [Recursion & Composition](docs/05_recursion-and-composition.md) - Function composition and mutual recursion
- [Error Handling](docs/06_error-handling.md) - `Result` types, validation, and debugging utilities
- [Syntax Gotchas](docs/07_gotchyas.md) - Common pitfalls and strict syntax requirements
- [Array Programming](docs/08_array-programming.md) - Comprehensive APL/K-inspired operations
- [JavaScript Interop](docs/09_js-interop.md) - Safe integration with JavaScript functions and APIs
### Technical Documentation
- [Lexer Bug Report](scratch/docs/LEXER_BUG_REPORT.md) - Critical issue with optimized lexer
- [Reimplementation Guide](scratch/docs/REIMPLEMENTATION_GUIDE.md) - Porting to Rust/C++
- [Build Instructions](scratch/docs/BUILD_README.md) - Static binary compilation
- [Cross-Compilation](scratch/docs/CROSS_COMPILATION_GUIDE.md) - Multi-platform builds
## Testing & Quality
- **Test Suite**: Over 200 tests covering all language features
- **Test Categories**: Parser, interpreter, functional enhancements, edge cases
- **Performance**: Benchmarking suite with optimization comparisons
- **Error Handling**: Rich error messages with source context and suggestions
## Known Issues
1. **Optimized Lexer Bug** (Critical) - Regex-based lexer skips file content
- **Status**: Documented, reverted to legacy lexer by default
- **Impact**: No user impact (legacy lexer works perfectly)
- **Fix**: Future investigation needed
## Conway's Game of Life
Working implementation demonstrating:
- Cellular automaton rules
- Pattern evolution (blinker oscillator)
- Game state management
```bash
bun run index.js scratch/baba/life-final.baba
```
|