diff options
Diffstat (limited to 'js/scripting-lang/README.md')
| -rw-r--r-- | js/scripting-lang/README.md | 320 |
1 files changed, 147 insertions, 173 deletions
diff --git a/js/scripting-lang/README.md b/js/scripting-lang/README.md index 73ccbf1..5890a06 100644 --- a/js/scripting-lang/README.md +++ b/js/scripting-lang/README.md @@ -1,220 +1,194 @@ -# Simple Scripting Language +# Baba Yaga +## A Scripting Language -A functional programming language with immutable variables, first-class functions, and pattern matching. +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. -## Features +This whole thing started as an aesthetic curiosity, and continued on from there. I wanted to be able to do pattern matching like this: -- **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`) +```plaintext +factorial : n -> + when n is + 0 then 1 + _ then n * (factorial (n - 1)); +``` -## Syntax +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. -### Basic Operations -``` -/* 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 and false; -or_result : true or false; -``` +Baba Yaga supports... -### Variables and Functions -``` -/* Immutable variables */ -x : 42; -y : "hello"; +- **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 */ -f : x -> x * 2; +factorial : n -> + when n is + 0 then 1 + _ then n * (factorial (n - 1)); -/* Function call */ -result : f 5; -``` +/* Function composition */ +double : x -> x * 2; +increment : x -> x + 1; +composed : compose @double @increment 5; +..out composed; -### Tables +/* 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; ``` -/* Table literal */ -table : {1, 2, 3, key: "value"}; -/* Table access */ -first : table[1]; -value : table.key; -nested : table.key.subkey; +Baba Yaga files should use either the `.txt` file extension, or the `.baba` extension. + +## Key Features + +### Function Application + +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 */ ``` ### Pattern Matching -``` -/* Case expression */ -result : case x of - 1 : "one" - 2 : "two" - _ : "other"; -``` -### IO Operations +Use `when` expressions for pattern matching: +```plaintext +result : when value is + 0 then "zero" + 1 then "one" + _ then "other"; ``` -/* Output */ -..out "Hello, World!"; -/* Input */ -name : ..in; +### Tables -/* Assertion */ -..assert x = 5; -``` +Create and access data structures: +```plaintext +/* Array-like */ +numbers : {1, 2, 3, 4, 5}; -### Standard Library +/* Key-value pairs */ +person : {name: "Beatrice", age: 26}; + +/* Boolean keys */ +flags : {true: "enabled", false: "disabled"}; ``` -/* Map */ -double : x -> x * 2; -squared : map @double 5; -/* Filter */ -isPositive : x -> x > 0; -filtered : filter @isPositive 5; +### Function References -/* Compose */ -f : x -> x + 1; -g : x -> x * 2; -h : compose @f @g; -result : h 5; /* (5 * 2) + 1 = 11 */ +Use the `@` to make reference to functions as arguments for other functions: +```plaintext +numbers : {1, 2, 3, 4, 5}; +doubled : map @double numbers; ``` -## Usage +## Combinators and Higher-Order Functions -### Running Scripts -```bash -node lang.js script.txt -``` +Baba Yaga tries to provide a comprehensive set of combinators for functional programming: -### 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 +### Core Combinators -# Run individual tests -node lang.js tests/01_lexer_basic.txt -node lang.js tests/integration_01_basic_features.txt -``` +- `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 -## Implementation Details +### Function Composition -### Architecture -- **Lexer**: Tokenizes input into tokens (numbers, identifiers, operators, etc.) -- **Parser**: Builds Abstract Syntax Tree (AST) from tokens -- **Interpreter**: Executes AST with scope management +- `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` -### 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 +### Table Operations -## Recent Fixes +All table operations are immutable so they return new tables. -### ✅ Parser Ambiguity with Unary Minus Arguments (Latest Fix) -- **Issue**: `filter @isPositive -3` was incorrectly parsed as binary operation instead of function call with unary minus argument -- **Root Cause**: Parser treating `FunctionReference MINUS` as binary minus operation -- **Solution**: Added special case in `parseExpression()` to handle `FunctionReference MINUS` pattern -- **Status**: ✅ Resolved - Standard library functions now work with negative arguments +- `t.map`, `t.filter`, `t.set`, `t.delete`, `t.merge`, `t.get`, `t.has`, `t.length` -### ✅ Unary Minus Operator -- **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 +### When to Use Which Combinator -### ✅ IO Operation Parsing -- **Issue**: IO operations not parsed correctly at top level -- **Solution**: Moved IO parsing to proper precedence level -- **Status**: ✅ Resolved +- Use `map` for general collections, `t.map` to emphasize table operations +- Use `map` for single-table transformations, `each` for combining multiple collections. -### ✅ Decimal Number Support -- **Issue**: Decimal numbers not handled correctly -- **Solution**: Updated lexer and interpreter to use `parseFloat()` -- **Status**: ✅ Resolved -## Known Issues +### Standard Library -### 🔄 Logical Operator Precedence -- **Issue**: Logical operators (`and`, `or`, `xor`) have incorrect precedence relative to function calls -- **Example**: `isEven 10 and isPositive 5` is parsed as `isEven(10 and isPositive(5))` instead of `(isEven 10) and (isPositive 5)` -- **Impact**: Complex expressions with logical operators may not evaluate correctly -- **Status**: 🔄 In Progress - Working on proper operator precedence hierarchy -- **Workaround**: Use parentheses to explicitly group expressions: `(isEven 10) and (isPositive 5)` +The language includes a comprehensive standard library: -### 🔄 Parentheses Parsing with Logical Operators -- **Issue**: Some expressions with logical operators inside parentheses fail to parse -- **Example**: `add (multiply 3 4) (isEven 10 and isPositive 5)` may fail with parsing errors -- **Status**: 🔄 In Progress - Related to logical operator precedence issue +**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` -## Development +## Architecture -### 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 +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 |