diff options
Diffstat (limited to 'js/baba-yaga/README.md')
| -rw-r--r-- | js/baba-yaga/README.md | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/js/baba-yaga/README.md b/js/baba-yaga/README.md new file mode 100644 index 0000000..947e91b --- /dev/null +++ b/js/baba-yaga/README.md @@ -0,0 +1,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 +``` |