diff options
Diffstat (limited to 'js/scripting-lang/baba-yaga-c/README.md')
| -rw-r--r-- | js/scripting-lang/baba-yaga-c/README.md | 395 |
1 files changed, 0 insertions, 395 deletions
diff --git a/js/scripting-lang/baba-yaga-c/README.md b/js/scripting-lang/baba-yaga-c/README.md deleted file mode 100644 index 5b2f8cd..0000000 --- a/js/scripting-lang/baba-yaga-c/README.md +++ /dev/null @@ -1,395 +0,0 @@ -# ð§ââïļ Baba Yaga C Implementation - -A complete C implementation of the Baba Yaga functional programming language featuring pattern matching, first-class functions, and interactive development. - -## ðŊ Current Status - -â **100% Complete** - All core functionality implemented and working -â **All tests passing** - Comprehensive test suite with full coverage -â **Production ready** - Stable, fast, and memory-safe implementation - -## ð Quick Start - -### Installation -```bash -# Clone and build -git clone <repository> -cd baba-yaga-c -make - -# Verify installation -./bin/baba-yaga -v -``` - -### Usage Modes - -```bash -# Interactive REPL (enhanced experience) -./bin/baba-yaga -r - -# Execute code directly -./bin/baba-yaga 'x : 42; ..out x' - -# Pipe-friendly (great for scripts) -echo 'factorial : n -> when n is 0 then 1 _ then n * (factorial (n - 1)); factorial 5' | ./bin/baba-yaga - -# Execute from file -./bin/baba-yaga -f script.txt - -# Run tests -./bin/baba-yaga -t tests/ -``` - -### First Examples - -```bash -# Basic arithmetic -./bin/baba-yaga '5 + 3 * 2' # => 11 - -# Variables and functions -./bin/baba-yaga 'x : 42; double : n -> n * 2; double x' # => 84 - -# Pattern matching -./bin/baba-yaga 'when 5 is 0 then "zero" _ then "other"' # => "other" - -# Output and interaction -./bin/baba-yaga '..out "Hello "; ..out "World"; 42' # Hello World => 42 - -# Recursive functions -./bin/baba-yaga 'factorial : n -> when n is 0 then 1 _ then n * (factorial (n - 1)); factorial 5' # => 120 -``` - -## ð Language Guide - -### Core Syntax - -#### Variables -```baba-yaga -x : 42 # Define variable -name : "Alice" # String variable -result : x + 10 # Computed variable -``` - -#### Functions -```baba-yaga -# Simple function -add : x y -> x + y - -# Multi-line function with pattern matching -factorial : n -> when n is 0 then 1 _ then n * (factorial (n - 1)) - -# Function calls -add 5 3 # => 8 -factorial 5 # => 120 -``` - -#### Pattern Matching -```baba-yaga -# Basic patterns -when x is 0 then "zero" _ then "other" - -# Multiple patterns -when x is - 0 then "zero" - 1 then "one" - 2 then "two" - _ then "other" - -# Multi-parameter patterns -classify : x y -> when x y is - 0 0 then "origin" - 0 _ then "y-axis" - _ 0 then "x-axis" - _ _ then "quadrant" -``` - -#### Tables (Objects/Maps) -```baba-yaga -# Table creation -person : {name: "Alice", age: 30} - -# Table access -person.name # => "Alice" -person["age"] # => 30 - -# Computed keys -key : "name" -person[key] # => "Alice" -``` - -#### IO Operations -All IO operations are namespaced with `..`: - -```baba-yaga -..out "Hello World"; 1 # Print to stdout, return 1 -..out 42; "done" # Print number, return "done" -..in # Read from stdin -..listen # Listen for events -..emit # Emit events -..assert # Assert conditions -``` - -### Advanced Features - -#### Function References -```baba-yaga -# Get function reference with @ -multiply : x y -> x * y -op : @multiply -op 3 4 # => 12 - -# Use in higher-order functions -numbers : [1, 2, 3, 4] -map @multiply numbers # Partial application -``` - -#### Partial Application -```baba-yaga -add : x y -> x + y -add5 : add 5 # Partial application -add5 3 # => 8 - -# Works with any function -multiply : x y -> x * y -double : multiply 2 -double 21 # => 42 -``` - -#### Recursive Functions -```baba-yaga -# Tail recursion supported -countdown : n -> when n is 0 then 0 _ then countdown (n - 1) - -# Mutual recursion -even : n -> when n is 0 then true _ then odd (n - 1) -odd : n -> when n is 0 then false _ then even (n - 1) -``` - -## ð ïļ Development - -### Build System -```bash -make # Build standard version (recommended) -make release # Build optimized release version -make debug # Build with debug symbols -make sanitize # Build with AddressSanitizer (memory debugging) -make clean # Clean build artifacts -make test # Run all tests -make memcheck # Build with sanitizers and run memory checks -``` - -**â ïļ Important:** Use `make release` for **production** and complex programs. The sanitizer builds (`make sanitize`, `make memcheck`) are only for **memory debugging** and can cause allocation issues on macOS. - -### Project Structure -``` -baba-yaga-c/ -âââ src/ # Source code -â âââ main.c # CLI and REPL -â âââ lexer.c # Tokenization -â âââ parser.c # AST generation -â âââ interpreter.c # Execution engine -â âââ function.c # Function calls and partial application -â âââ stdlib.c # Standard library functions -â âââ ... -âââ include/ -â âââ baba_yaga.h # Public API -âââ tests/ # Comprehensive test suite -âââ bin/ # Built executables -âââ obj/ # Build artifacts -``` - -### Testing -```bash -# Run full test suite -make test -# or -./bin/baba-yaga -t tests/ - -# Run comprehensive bash test suite -./run_tests.sh - -# Test with debug output -DEBUG=5 ./bin/baba-yaga 'factorial 5' - -# Memory error checking (on macOS) -# For memory debugging only (can cause allocation issues): -make sanitize -ASAN_OPTIONS=abort_on_error=1 ./bin/baba-yaga 'factorial : n -> when n is 0 then 1 _ then n * (factorial (n - 1)); factorial 10;' - -# For normal use, build clean release version: -make release -``` - -### Debugging -The implementation includes comprehensive debug logging: - -```bash -DEBUG=0 # No debug output (default) -DEBUG=1 # Errors only -DEBUG=2 # Warnings and errors -DEBUG=3 # Info, warnings, and errors -DEBUG=4 # Debug messages -DEBUG=5 # All messages including trace -``` - -### Contributing - -1. **Code Style**: Follow the existing C style with 4-space indentation -2. **Testing**: Add tests for new features in the `tests/` directory -3. **Documentation**: Update README and ROADMAP for significant changes -4. **Memory Safety**: All code must be memory-safe (no leaks, no corruption) -5. **Performance**: Maintain O(1) for basic operations, document complexity for others - -### Architecture - -#### Core Components - -- **Lexer** (`src/lexer.c`): Tokenizes source code into tokens -- **Parser** (`src/parser.c`): Builds Abstract Syntax Tree (AST) from tokens -- **Interpreter** (`src/interpreter.c`): Evaluates AST nodes recursively -- **Function System** (`src/function.c`): Handles calls, partial application, recursion -- **Memory Management** (`src/memory.c`, `src/value.c`): Safe memory handling -- **Standard Library** (`src/stdlib.c`): Built-in functions and operations - -#### Key Design Decisions - -- **Value-based**: All data is immutable `Value` structs -- **Reference counting**: Automatic memory management for complex types -- **Eager evaluation**: Arguments evaluated before function calls -- **Lexical scoping**: Variables resolved at definition time -- **Pattern matching**: Compile-time optimization for common patterns - -## ð Language Semantics - -### Evaluation Model -Baba Yaga uses **eager evaluation** with **lexical scoping**: - -1. **Expressions** are evaluated left-to-right -2. **Function arguments** are evaluated before the function call -3. **Variables** are resolved in lexical scope order -4. **Pattern matching** uses first-match semantics - -### Type System -Baba Yaga is **dynamically typed** with these core types: - -- `Number` - 64-bit floating point -- `String` - UTF-8 text -- `Boolean` - true/false -- `Function` - First-class functions -- `Table` - Key-value mappings -- `Nil` - Absence of value - -### Memory Model -- **Immutable values** - All data is immutable by default -- **Reference counting** - Automatic cleanup of complex types -- **Copy semantics** - Values are copied on assignment -- **Scope-based cleanup** - Variables cleaned up when leaving scope - -### Error Handling -- **Parse errors** - Syntax errors caught at parse time -- **Runtime errors** - Type errors and undefined variables caught at runtime -- **Graceful degradation** - Errors don't crash the interpreter -- **Error recovery** - REPL continues after errors - -## ðŪ Interactive REPL - -The enhanced REPL provides a rich development experience: - -```bash -./bin/baba-yaga -r -``` - -### REPL Features -- **Syntax highlighting** - Clear visual feedback -- **Built-in help** - Type `help` for language guide -- **Multi-line support** - Continue expressions across lines -- **Error recovery** - Continue working after errors -- **Clean output** - Results prefixed with `=>` - -### REPL Commands -- `help` - Show language guide and commands -- `clear` - Clear the screen -- `exit` or `quit` - Exit the REPL - -## ð§ Command Line Options - -```bash -Usage: ./bin/baba-yaga [OPTIONS] [SOURCE_CODE] - -Options: - -h Show help message - -v Show version information - -r Start interactive REPL mode - -f FILE Execute source code from file - -t DIR Run tests from directory - -Examples: - ./bin/baba-yaga # Execute from stdin (pipe-friendly) - ./bin/baba-yaga -r # Start interactive REPL - ./bin/baba-yaga -f script.txt # Execute file - ./bin/baba-yaga 'x : 42; ..out x' # Execute code - ./bin/baba-yaga -t tests/ # Run tests -``` - -## ð Performance - -The implementation is optimized for: -- **Fast startup** - Minimal initialization overhead -- **Low memory usage** - Efficient value representation -- **Quick function calls** - Optimized call stack -- **Pattern matching** - Compile-time optimization - -Typical performance: -- **Simple expressions**: < 1ms -- **Function calls**: < 10Ξs overhead -- **Pattern matching**: O(1) for most patterns -- **Memory usage**: ~1KB base + data size - -## ð Troubleshooting - -### Common Issues - -**Syntax Errors** -```bash -# Wrong: Missing semicolon in sequence -./bin/baba-yaga 'x : 42 y : 24' - -# Right: Proper sequence syntax -./bin/baba-yaga 'x : 42; y : 24' -``` - -**IO Namespace** -```bash -# Wrong: Missing namespace -./bin/baba-yaga 'out "hello"' - -# Right: Proper IO namespace -./bin/baba-yaga '..out "hello"' -``` - -**Pattern Matching** -```bash -# Wrong: Missing underscore for default case -./bin/baba-yaga 'when x is 0 then "zero"' - -# Right: Include default case -./bin/baba-yaga 'when x is 0 then "zero" _ then "other"' -``` - -### Debug Tips -1. Use `DEBUG=5` for full trace output -2. Test expressions in REPL first -3. Check syntax with simple examples -4. Use `make release` for production; `make sanitize && make memcheck` only for memory debugging - -## ð License - -[License information - please specify your chosen license] - -## ð Acknowledgments - -Built with modern C practices, comprehensive testing, and attention to memory safety and performance. - ---- - -*For detailed implementation notes and development roadmap, see [ROADMAP.md](ROADMAP.md)* \ No newline at end of file |