diff options
Diffstat (limited to 'js/scripting-lang/README.md')
| -rw-r--r-- | js/scripting-lang/README.md | 327 |
1 files changed, 158 insertions, 169 deletions
diff --git a/js/scripting-lang/README.md b/js/scripting-lang/README.md index e55646c..5890a06 100644 --- a/js/scripting-lang/README.md +++ b/js/scripting-lang/README.md @@ -1,205 +1,194 @@ -# Simple Scripting Language - -A functional programming language with immutable variables, first-class functions, and pattern matching. - -## Features - -- **Immutable Variables**: Variables cannot be reassigned -- **First-Class Functions**: Functions can be passed as arguments and stored in data structures -- **Lexical Scoping**: Functions create their own scope -- **Pattern Matching**: Case expressions with wildcard support -- **Table Literals**: Lua-style tables with both array-like and key-value entries -- **Standard Library**: Built-in higher-order functions (`map`, `compose`, `pipe`, `apply`, `filter`, `reduce`, `fold`, `curry`) -- **IO Operations**: Built-in input/output operations (`..in`, `..out`, `..assert`) -- **Floating Point Arithmetic**: Full support for decimal numbers -- **Unary Minus**: Support for negative numbers (e.g., `-1`, `-3.14`) - -## Syntax - -### Basic Operations -```javascript -// Arithmetic -x = 5 + 3 -y = 10 - 2 -z = 4 * 3 -w = 15 / 3 -neg = -5 // Unary minus - -// Comparisons -result = x > y -equal = a == b -not_equal = a != b - -// Logical -and_result = true && false -or_result = true || false -``` +# Baba Yaga +## A Scripting Language -### Variables and Functions -```javascript -// Immutable variables -x = 42 -y = "hello" +Baba Yaga is a combinator-based scripting language that aims to be dangerously functional-brained, has minimal syntax, an intuitive approach to pattern matching, and hopefully enough of a standard library to be useful...but not too much of a standard library to be difficult to recall. -// Function definition -f = (x) => x * 2 +This whole thing started as an aesthetic curiosity, and continued on from there. I wanted to be able to do pattern matching like this: -// Function call -result = f(5) +```plaintext +factorial : n -> + when n is + 0 then 1 + _ then n * (factorial (n - 1)); ``` -### Tables -```javascript -// Table literal -table = [1, 2, 3, key: "value"] - -// Table access -first = table[0] -value = table.key -nested = table.key.subkey +I've implemented a whole bunch of [forths](https://git.sr.ht/~eli_oat/chupacabra), and a couple schemes, but never have I ever implemented something like a "regular" programming language. And, while, an [ML-flavored](https://en.wikipedia.org/wiki/Standard_ML) programming language isn't exactly regular, this has grown from an aesthetic curiosity to a full-blown aesthetic indulgence. + +Baba Yaga supports... + +- **Function definitions** using arrow syntax with lexical scoping +- **Pattern matching** with a single `when ... is ... then` expression that handles wildcards and arbitrarily nested features +- **Tables** inspired by Lua's tables, with array-like and key-value entries, including boolean keys +- **Function references** using an `@` operator for higher-order programming +- **IO Operations** including input, output, and assertions, plus an `..emit` and `..listen` pattern for interfacing a functional core with the outside world. This contains side effects to a very limited surface area +- **Standard Library** with a complete set of arithmetic, comparison, logical, and higher-order combinators...I think (let me know if I'm missing anything) +- **APL-style operations** with element-wise and immutable table operations so that you can use broadcasting instead of looping +- **Function composition** with `compose`, `pipe`, and `via` operators, supporting a bunch of different ways to chain functions together +- **Currying by default** - all functions are automatically curried +- **Combinator-based architecture** everything is "just" a function call or reference under the hood...because this supposedly made parsing easier...but I'm not yet totally sold on that reasoning + +## Example Script +```plaintext +/* Basic arithmetic */ +result : 5 + 3 * 2; +..out result; + +/* Function definition */ +factorial : n -> + when n is + 0 then 1 + _ then n * (factorial (n - 1)); + +/* Function composition */ +double : x -> x * 2; +increment : x -> x + 1; +composed : compose @double @increment 5; +..out composed; + +/* Pattern matching */ +classify : x y -> + when x y is + 0 0 then "both zero" + 0 _ then "x is zero" + _ 0 then "y is zero" + _ _ then "neither zero"; + +/* Tables */ +person : {name: "Baba Yaga", age: 99, active: true}; +..out person.name; +..out person["age"]; + +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; +..out doubled[1]; + +/* APL-style element-wise operations over tables */ +table1 : {a: 1, b: 2, c: 3}; +table2 : {a: 10, b: 20, c: 30}; +sum : each @add table1 table2; +..out sum.a; ``` -### Pattern Matching -```javascript -// Case expression -result = case x of - 1 => "one" - 2 => "two" - _ => "other" -``` +Baba Yaga files should use either the `.txt` file extension, or the `.baba` extension. -### IO Operations -```javascript -// Output -..out "Hello, World!" +## Key Features -// Input -name = ..in +### Function Application -// Assertion -..assert x == 5 +Functions are applied using juxtaposition (space-separated), and you can use parentheses to help disambiguate precedence: +```plaintext +f x /* Apply function f to argument x */ +f x y /* Apply f to x, then apply result to y */ +f (g x) /* Apply g to x, then apply f to result */ ``` -### Standard Library -```javascript -// Map -squared = map((x) => x * x, [1, 2, 3, 4]) - -// Filter -evens = filter((x) => x % 2 == 0, [1, 2, 3, 4, 5]) - -// Compose -f = (x) => x + 1 -g = (x) => x * 2 -h = compose(f, g) -result = h(5) // (5 * 2) + 1 = 11 +### Pattern Matching + +Use `when` expressions for pattern matching: +```plaintext +result : when value is + 0 then "zero" + 1 then "one" + _ then "other"; ``` -## Usage +### Tables + +Create and access data structures: +```plaintext +/* Array-like */ +numbers : {1, 2, 3, 4, 5}; -### Running Scripts -```bash -node lang.js script.txt +/* Key-value pairs */ +person : {name: "Beatrice", age: 26}; + +/* Boolean keys */ +flags : {true: "enabled", false: "disabled"}; ``` -### Testing -The project uses a structured testing approach with unit and integration tests: - -#### Unit Tests -Located in `tests/` directory, each focusing on a specific language feature: -- `01_lexer_basic.txt` - Basic lexer functionality -- `02_arithmetic_operations.txt` - Arithmetic operations -- `03_comparison_operators.txt` - Comparison operators -- `04_logical_operators.txt` - Logical operators -- `05_io_operations.txt` - IO operations -- `06_function_definitions.txt` - Function definitions -- `07_case_expressions.txt` - Case expressions and pattern matching -- `08_first_class_functions.txt` - First-class function features -- `09_tables.txt` - Table literals and access -- `10_standard_library.txt` - Standard library functions - -#### Integration Tests -Test combinations of multiple features: -- `integration_01_basic_features.txt` - Basic feature combinations -- `integration_02_pattern_matching.txt` - Pattern matching with other features -- `integration_03_functional_programming.txt` - Functional programming patterns - -#### Running Tests -```bash -# Run all tests -./run_tests.sh +### Function References -# Run individual tests -node lang.js tests/01_lexer_basic.txt -node lang.js tests/integration_01_basic_features.txt +Use the `@` to make reference to functions as arguments for other functions: +```plaintext +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; ``` -## Implementation Details +## Combinators and Higher-Order Functions -### Architecture -- **Lexer**: Tokenizes input into tokens (numbers, identifiers, operators, etc.) -- **Parser**: Builds Abstract Syntax Tree (AST) from tokens -- **Interpreter**: Executes AST with scope management +Baba Yaga tries to provide a comprehensive set of combinators for functional programming: -### Key Components -- **Token Types**: Supports all basic operators, literals, and special tokens -- **AST Nodes**: Expression, statement, and declaration nodes -- **Scope Management**: Lexical scoping with proper variable resolution -- **Error Handling**: Comprehensive error reporting for parsing and execution +### Core Combinators -## Recent Fixes +- `map f x` - Transform elements in collections +- `filter p x` - Select elements based on predicates +- `reduce f init x` - Accumulate values into a single result +- `each f x` - Multi-argument element-wise operations -### ✅ Unary Minus Operator (Latest Fix) -- **Issue**: Stack overflow when parsing negative numbers (e.g., `-1`) -- **Root Cause**: Parser lacked specific handling for unary minus operator -- **Solution**: Added `UnaryMinusExpression` parsing and evaluation -- **Status**: ✅ Resolved - All tests passing +### Function Composition -### ✅ IO Operation Parsing -- **Issue**: IO operations not parsed correctly at top level -- **Solution**: Moved IO parsing to proper precedence level -- **Status**: ✅ Resolved +- `compose f g` - Right-to-left composition (mathematical style) +- `pipe f g` - Left-to-right composition (pipeline style) +- `via` - Kinda like `.` composition syntax: `f via g via h` -### ✅ Decimal Number Support -- **Issue**: Decimal numbers not handled correctly -- **Solution**: Updated lexer and interpreter to use `parseFloat()` -- **Status**: ✅ Resolved +### Table Operations -## Known Issues +All table operations are immutable so they return new tables. -### 🔄 Multi-Parameter Case Expressions in Function Bodies -- **Issue**: Parsing error when multi-parameter case expressions appear inside functions -- **Status**: 🔄 In Progress - Issue identified, fix pending -- **Workaround**: Use single-parameter case expressions or place multi-parameter cases outside functions +- `t.map`, `t.filter`, `t.set`, `t.delete`, `t.merge`, `t.get`, `t.has`, `t.length` -## Development +### When to Use Which Combinator -### File Structure -``` -. -├── lang.js # Main implementation -├── test.txt # Comprehensive test file -├── tests/ # Unit and integration tests -│ ├── 01_lexer_basic.txt -│ ├── 02_arithmetic_operations.txt -│ ├── ... -│ ├── integration_01_basic_features.txt -│ ├── integration_02_pattern_matching.txt -│ └── integration_03_functional_programming.txt -├── run_tests.sh # Test runner script -├── FIXME.md # Issues and fixes documentation -└── README.md # This file +- Use `map` for general collections, `t.map` to emphasize table operations +- Use `map` for single-table transformations, `each` for combining multiple collections. + + +### Standard Library + +The language includes a comprehensive standard library: + +**Arithmetic**: `add`, `subtract`, `multiply`, `divide`, `modulo`, `power`, `negate` +**Comparison**: `equals`, `notEquals`, `lessThan`, `greaterThan`, `lessEqual`, `greaterEqual` +**Logical**: `logicalAnd`, `logicalOr`, `logicalXor`, `logicalNot` +**Higher-Order**: `map`, `compose`, `pipe`, `apply`, `filter`, `reduce`, `fold`, `curry`, `each` +**Enhanced**: `identity`, `constant`, `flip`, `on`, `both`, `either` +**Table Operations**: `t.map`, `t.filter`, `t.set`, `t.delete`, `t.merge`, `t.get`, `t.has`, `t.length` + +## Architecture + +Baba Yaga uses a combinator-based architecture where all operations are translated to function calls: + +1. **Lexer**: Converts source code into tokens +2. **Parser**: Translates tokens into AST, converting operators to combinator calls +3. **Interpreter**: Executes combinator functions from the standard library + +The idea behind this approach is that it should eliminate parsing ambiguity while preserving syntax and enabling functional programming patterns like currying and composition, but the implementation is likely a little bit janky. + +## Testing + +Run the complete test suite! +```bash +./run_tests.sh ``` -### Debugging -Enable debug mode by setting `DEBUG=true`: +This assumes you are using bun, but I've also tested extensively with both node and the browser, too. I haven't validated it, yet, but I think Baba Yaga should work with quickjs, too. + +### Debug Mode + +Enable debug output for development using the flag `DEBUG=1` or `DEBUG=2`: ```bash -DEBUG=true node lang.js script.txt +DEBUG=1 node lang.js your-script.txt ``` -## Contributing +This'll output a lot of debug info, including the AST (as JSON). + +### Adding Features + +If you wanna add language features, the easiest way to do it is to see if you can implement them in Baba Yaga script, if you need to get into the guts of the thing, though, you wanna follow this pattern, -1. Create focused unit tests for new features -2. Add integration tests for feature combinations -3. Update documentation -4. Run the full test suite before submitting changes \ No newline at end of file +1. Add tests in `tests/` +2. Add tokens in `lexer.js` +3. Add parsing logic in `parser.js` +4. Add evaluation logic in `lang.js` +5. Validate against the tests you added earlier +6. Update documentation \ No newline at end of file |