# 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 ```