diff options
Diffstat (limited to 'js/scripting-lang/README.md')
| -rw-r--r-- | js/scripting-lang/README.md | 804 |
1 files changed, 254 insertions, 550 deletions
diff --git a/js/scripting-lang/README.md b/js/scripting-lang/README.md index 9ab36e4..08334a4 100644 --- a/js/scripting-lang/README.md +++ b/js/scripting-lang/README.md @@ -1,607 +1,311 @@ # Simple Scripting Language -A minimal, interpreted scripting language designed for learning language implementation concepts. This language demonstrates the core components needed for an interpreter: lexer, parser, and interpreter. +A functional programming language with immutable variables, first-class functions, and pattern matching, built on a combinator-based foundation. ## Features -- **Arithmetic operations**: `+`, `-`, `*`, `/`, `%` (modulo), `^` (power) -- **Comparison operators**: `=`, `<`, `>`, `<=`, `>=`, `!=` -- **Logical operators**: `and`, `or`, `xor`, `not` -- **Variable assignment**: Immutable variables with `:` syntax -- **Function definitions**: Arrow function syntax with pattern matching -- **Pattern matching**: Case expressions with wildcard support -- **Function calls**: Direct function application -- **First-class functions**: Functions can be passed as arguments using `@` syntax -- **Function composition**: Higher-order functions for combining functions -- **Lexical scoping**: Functions create their own scope -- **Input/Output**: Built-in IO operations with `..in`, `..out`, and `..assert` -- **Standard Library**: Built-in functional programming utilities -- **Comments**: C-style block comments with `/* ... */` syntax +- **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`) +- **Combinator Foundation**: All operations are implemented as function calls under the hood +- **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`) + +## Current Implementation Status + +### ✅ Completed Features +- **Core Combinators**: All arithmetic, comparison, logical, and higher-order combinators implemented +- **Parser Translation**: All operators translated to combinator function calls +- **Syntax Preservation**: All existing syntax works unchanged +- **Standard Library**: Complete set of higher-order functions +- **Basic Operations**: Arithmetic, comparison, logical operations +- **Function Definitions**: Arrow functions and function declarations +- **Tables**: Table literals and bracket notation access +- **IO Operations**: Input, output, and assertions + +### 🔄 In Progress +- **Recursive Functions**: Support for functions that call themselves +- **Advanced Pattern Matching**: Extended when expression patterns +- **Dot Notation**: Table access with dot notation (`table.property`) +- **Multi-parameter Cases**: Case expressions with multiple parameters ## Syntax -### Variables - -Variables are immutable and assigned using the `:` operator: - +### Basic Operations ``` -x : 5; -y : 10; -``` - -### Arithmetic Operations +/* Arithmetic */ +x : 5 + 3; +y : 10 - 2; +z : 4 * 3; +w : 15 / 3; +neg : -5; /* Unary minus */ -Arithmetic operations are supported with parentheses grouping: +/* Comparisons */ +result : x > y; +equal : a = b; +not_equal : a != b; +/* Logical */ +and_result : true and false; +or_result : true or false; ``` -sum : x + y; -diff : x - y; -product : x * y; -quotient : x / y; -modulo : 17 % 5; /* Returns 2 */ -power : 2 ^ 3; /* Returns 8 */ -grouped : (5 + 3) * 2; /* Returns 16 */ -nested : ((5 + 3) * 2) + 1; /* Returns 17 */ -``` - -### Function Definitions -Functions are defined using arrow syntax (`->`): - -``` -add : x y -> x + y; -double : x -> x * 2; +### Variables and Functions ``` +/* Immutable variables */ +x : 42; +y : "hello"; -### Function Calls - -Functions are called by providing arguments directly after the function name: +/* Function definition */ +f : x -> x * 2; +/* Function call */ +result : f 5; ``` -result : add 3 4; -doubled : double 5; -``` - -#### Function Calls with Parentheses - -Function calls support parenthesized arguments for complex expressions: +### Tables ``` -/* Simple function call */ -result1 : add 3 4; - -/* Function call with parenthesized arithmetic */ -result2 : add (3 + 2) (4 + 1); +/* Table literal */ +table : {1, 2, 3, key: "value"}; -/* Function call with function calls in parentheses */ -result3 : add (double 3) (square 2); - -/* Complex nested function calls with parentheses */ -result4 : add (add 1 2) (add 3 4); +/* Table access */ +first : table[1]; +value : table.key; /* Coming soon */ +nested : table.key.subkey; /* Coming soon */ ``` -**Note:** Parentheses provide explicit grouping and are the recommended way to handle complex nested function calls. - -### First-Class Functions - -Functions can be passed as arguments to other functions using the `@` prefix: - -``` -double : x -> x * 2; -square : x -> x * x; -compose : f g x -> f g x; - -composed : compose @double @square 3; /* double(square(3)) = 18 */ -``` - -**Function Reference Syntax:** -- `@functionName` - Creates a function reference (doesn't execute the function) -- `functionName args` - Calls the function with arguments - ### Pattern Matching - -The language supports pattern matching with case expressions in function bodies: - -``` -compare : x y -> - case x y of - 0 0 : "both zero" - 0 _ : "x is zero" - _ 0 : "y is zero" - _ _ : "neither zero"; -``` - -#### Pattern Matching Syntax - -- **Exact matches**: `0 0` matches when both values are 0 -- **Wildcards**: `_` matches any value -- **Mixed patterns**: `0 _` matches when first value is 0 and second can be anything - -### Comparison and Logical Operations - -The language supports comparison and logical operations: - -``` -/* Comparison operators */ -less : 3 < 5; /* true */ -greater : 10 > 5; /* true */ -equal : 5 = 5; /* true */ -not_equal : 3 != 5; /* true */ -less_equal : 5 <= 5; /* true */ -greater_equal : 5 >= 3; /* true */ - -/* Logical operators */ -and_result : 1 and 1; /* true */ -or_result : 0 or 1; /* true */ -xor_result : 1 xor 0; /* true */ -not_result : not 0; /* true */ -``` - -### Comments - -The language supports C-style block comments: - -``` -/* This is a single line comment */ - -/* This is a multi-line comment - that spans multiple lines */ - -x : 5; /* Comment on same line as code */ - -/* Nested comments are supported */ -/* Outer comment /* Inner comment */ More outer comment */ -``` - -**Comment Features:** -- Block comments start with `/*` and end with `*/` -- Comments can span multiple lines -- Comments can appear on the same line as code -- Nested comments are supported -- Comments are completely ignored by the lexer and parser - -### Input/Output Operations - -The language provides built-in IO operations for reading from stdin and writing to stdout: - -``` -name : ..in; /* Read input from stdin */ -..out name; /* Output to stdout */ -..out "Hello"; /* Output string literal */ -..out 42; /* Output number */ -..assert x = 5; /* Assert that x equals 5 */ -..assert y > 3; /* Assert that y is greater than 3 */ -..assert z != 0; /* Assert that z is not equal to 0 */ -``` - -**IO Functions:** -- `..in` - Reads a line from stdin, returns a number if possible, otherwise a string -- `..out` - Outputs a value to stdout and returns the value -- `..assert` - Asserts that a comparison is true, throws an error if it's false. Supports all comparison operators: `=`, `<`, `>`, `<=`, `>=`, `!=` - -**Note:** The `..` prefix indicates these are impure operations that have side effects. - -## Standard Library - -The language includes a built-in standard library with functional programming utilities: - -### Higher-Order Functions - -- **map**: Apply a function to a value (`map f x = f x`) -- **compose**: Compose two functions (`compose f g x = f(g(x))`) -- **curry**: Explicit currying (`curry f x y = f x y`) -- **apply**: Apply a function to an argument (`apply f x = f x`) -- **pipe**: Compose functions left-to-right (`pipe f g x = g(f(x))`) -- **filter**: Filter based on a predicate (`filter p x = p(x) ? x : 0`) -- **reduce**: Reduce to a single value (`reduce f init x = f(init, x)`) -- **fold**: Same as reduce (`fold f init x = f(init, x)`) - -### Usage Examples - -``` -double : x -> x * 2; -square : x -> x * x; - -/* Using map */ -result1 : map @double 5; /* Returns 10 */ -result2 : map @square 3; /* Returns 9 */ - -/* Using compose */ -composed : compose @double @square 3; /* double(square(3)) = 18 */ - -/* Using pipe */ -piped : pipe @double @square 2; /* square(double(2)) = 16 */ - -/* Using filter */ -isPositive : x -> x > 0; -filtered : filter @isPositive 5; /* Returns 5 (since 5 > 0) */ -``` - - - -## Language Components - -### Lexer - -The lexer tokenizes input into meaningful units: -- Numbers: `123` -- Identifiers: `variable_name` -- Operators: `+`, `-`, `*`, `/` -- Keywords: `case`, `of`, `function` -- Symbols: `:`, `->`, `_` - -### Parser - -The parser builds an Abstract Syntax Tree (AST) from tokens, supporting: -- Number literals -- Arithmetic expressions -- Variable assignments -- Function declarations -- Function calls -- Case expressions -- Pattern matching - -### Interpreter - -The interpreter executes the AST with: -- Global scope management -- Function evaluation -- Pattern matching execution -- Arithmetic computation -- Immutable variable semantics - -## Example Programs - -### Basic Arithmetic and Variables - ``` -/* Simple arithmetic with variables */ -x : 5; -y : 10; -sum : x + y; -diff : x - y; -product : x * y; -quotient : y / x; -modulo : 17 % 5; /* Returns 2 */ -power : 2 ^ 3; /* Returns 8 */ - -..out sum; /* 15 */ -..out diff; /* -5 */ -..out product; /* 50 */ -..out quotient; /* 2 */ -..out modulo; /* 2 */ -..out power; /* 8 */ - -/* Grouped expressions with parentheses */ -grouped : (5 + 3) * 2; /* 16 */ -nested : ((5 + 3) * 2) + 1; /* 17 */ -complex : (2 ^ 3) % 3 and 5 > 3; /* true */ +/* Case expression */ +result : when x is + 1 then "one" + 2 then "two" + _ then "other"; ``` -### Function Definitions and Calls - -``` -/* Basic function definition */ -add : x y -> x + y; -multiply : x y -> x * y; -double : x -> x * 2; -square : x -> x * x; - -/* Function calls */ -result1 : add 3 4; /* 7 */ -result2 : multiply 5 6; /* 30 */ -result3 : double 8; /* 16 */ -result4 : square 4; /* 16 */ - -/* Function calls with parenthesized arguments */ -result5 : add (3 + 2) (4 + 1); /* 15 */ -result6 : add (double 3) (square 2); /* 10 */ -result7 : add (add 1 2) (add 3 4); /* 10 */ +### IO Operations ``` +/* Output */ +..out "Hello, World!"; -### Pattern Matching with Case Expressions +/* Input */ +name : ..in; +/* Assertion */ +..assert x = 5; ``` -/* Pattern matching in function bodies */ -compare : x y -> - case x y of - 0 0 : "both zero" - 0 _ : "x is zero" - _ 0 : "y is zero" - _ _ : "neither zero"; - -/* Testing pattern matching */ -test1 : compare 0 0; /* "both zero" */ -test2 : compare 0 5; /* "x is zero" */ -test3 : compare 5 0; /* "y is zero" */ -test4 : compare 5 5; /* "neither zero" */ - -/* Single-parameter case expressions */ -factorial : n -> - case n of - 0 : 1 - _ : n * (factorial (n - 1)); - -/* Single-parameter grade function */ -grade : score -> - case score of - 90 : "A" - 80 : "B" - 70 : "C" - _ : "F"; - -fact5 : factorial 5; /* 120 */ -grade1 : grade 95; /* "A" */ -grade2 : grade 85; /* "B" */ -grade3 : grade 65; /* "F" */ -``` - -### First-Class Functions and Composition +### Standard Library ``` -/* Function references and composition */ +/* Map */ double : x -> x * 2; -square : x -> x * x; -add1 : x -> x + 1; - -/* Using standard library functions */ -composed : compose @double @square 3; /* double(square(3)) = 18 */ -piped : pipe @double @square 2; /* square(double(2)) = 16 */ -applied : apply @double 5; /* double(5) = 10 */ - -/* Higher-order functions */ -mapped1 : map @double 5; /* 10 */ -mapped2 : map @square 3; /* 9 */ - -/* Function references in case expressions */ -getFunction : type -> - case type of - "double" : @double - "square" : @square - _ : @add1; - -func1 : getFunction "double"; /* Function reference */ -func2 : getFunction "square"; /* Function reference */ -``` - -### Recursion and Complex Functions - -``` -/* Recursive factorial function (using single-parameter case) */ -factorial : n -> - case n of - 0 : 1 - _ : n * (factorial (n - 1)); - -/* Recursive countdown function */ -countdown : n -> - case n of - 0 : "done" - _ : countdown (n - 1); - -/* Testing recursive functions */ -fact5 : factorial 5; /* 120 */ -count : countdown 3; /* "done" */ -``` - -### Comparison and Logical Operators - -``` -/* Comparison operators */ -a : 5; -b : 10; - -less : a < b; /* true */ -greater : b > a; /* true */ -equal : a = a; /* true */ -notEqual : a != b; /* true */ -lessEqual : a <= 5; /* true */ -greaterEqual : b >= 10; /* true */ - -/* Logical operators */ -logicalAnd : 1 and 1; /* true */ -logicalOr : 0 or 1; /* true */ -logicalXor : 1 xor 0; /* true */ -logicalNot : not 0; /* true */ - -/* Complex logical expressions */ -complex1 : a < b and b > 5; /* true */ -complex2 : a = 5 or b = 15; /* true */ -complex3 : not (a = b); /* true */ -``` +squared : map @double 5; -### Input/Output and Assertions - -``` -/* Interactive input/output */ -..out "Enter your name: "; -name : ..in; -..out "Hello, "; -..out name; -..out "!"; - -/* Assertions for testing */ -x : 5; -y : 3; -sum : x + y; - -..assert x = 5; /* Passes */ -..assert y = 3; /* Passes */ -..assert sum = 8; /* Passes */ -..assert x > 3; /* Passes */ -..assert y < 10; /* Passes */ -..assert sum != 0; /* Passes */ -..assert (add 3 4) = 7; /* Passes (with parentheses) */ - -/* String comparisons */ -..assert "hello" = "hello"; /* Passes */ -..assert "world" != "hello"; /* Passes */ -``` - -### Standard Library Functions - -``` -/* Using all standard library functions */ -double : x -> x * 2; -square : x -> x * x; -add : x y -> x + y; +/* Filter */ isPositive : x -> x > 0; +filtered : filter @isPositive 5; -/* Map function */ -mapped1 : map @double 5; /* 10 */ -mapped2 : map @square 3; /* 9 */ - -/* Compose function */ -composed : compose @double @square 3; /* 18 */ - -/* Pipe function */ -piped : pipe @double @square 2; /* 16 */ - -/* Apply function */ -applied : apply @double 7; /* 14 */ - -/* Filter function */ -filtered : filter @isPositive 5; /* 5 (since 5 > 0) */ -filtered2 : filter @isPositive -3; /* 0 (since -3 <= 0) */ - -/* Reduce and Fold functions */ -reduced : reduce @add 0 5; /* 5 */ -folded : fold @add 0 5; /* 5 */ - -/* Curry function (explicit currying) */ -curried : curry @add 3 4; /* 7 */ -``` - -### Complete Program Example - -``` -/* A complete program demonstrating multiple features */ -..out "Welcome to the Calculator!"; - -/* Define arithmetic functions */ -add : x y -> x + y; -subtract : x y -> x - y; -multiply : x y -> x * y; -divide : x y -> x / y; - -/* Define utility functions */ -double : x -> x * 2; -square : x -> x * x; -isEven : x -> x % 2 = 0; - -/* Get user input */ -..out "Enter first number: "; -num1 : ..in; -..out "Enter second number: "; -num2 : ..in; - -/* Perform calculations */ -sum : add num1 num2; -diff : subtract num1 num2; -prod : multiply num1 num2; -quot : divide num1 num2; - -/* Display results */ -..out "Sum: "; -..out sum; -..out "Difference: "; -..out diff; -..out "Product: "; -..out prod; -..out "Quotient: "; -..out quot; - -/* Use higher-order functions */ -doubledSum : double sum; -squaredDiff : square diff; - -..out "Doubled sum: "; -..out doubledSum; -..out "Squared difference: "; -..out squaredDiff; - -/* Pattern matching for number classification */ -classify : num -> - case num of - 0 : "zero" - _ : case isEven num of - true : "even" - _ : "odd"; - -classification : classify num1; -..out "First number is: "; -..out classification; - -/* Assertions to verify calculations */ -..assert sum = add num1 num2; -..assert diff = subtract num1 num2; -..assert prod = multiply num1 num2; - -..out "All calculations verified!"; +/* Compose */ +f : x -> x + 1; +g : x -> x * 2; +h : compose @f @g; +result : h 5; /* (5 * 2) + 1 = 11 */ ``` -## Running Programs - -The language supports two modes of execution: - -### File Execution Mode -Run a script file by providing the file path as an argument: +## Usage +### Running Scripts ```bash node lang.js script.txt ``` -### REPL Mode -Start an interactive REPL by running without arguments: - +### 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 ✅ +- `11_edge_cases.txt` - Edge cases 🔄 +- `12_advanced_tables.txt` - Advanced table features 🔄 +- `13_standard_library_complete.txt` - Complete standard library ✅ +- `14_error_handling.txt` - Error handling 🔄 +- `15_multi_parameter_case.txt` - Multi-parameter case expressions 🔄 + +#### 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 -node lang.js +# Run all tests +./run_tests.sh + +# Run individual tests +node lang.js tests/01_lexer_basic.txt +node lang.js tests/integration_01_basic_features.txt +# or with bun +bun run lang.js tests/01_lexer_basic.txt ``` -In REPL mode: -- Type expressions and end them with a semicolon (`;`) to execute -- Multi-line expressions are supported -- Type `exit` or `quit` to exit -- Variables and functions persist between expressions +## Implementation Details +### Architecture +- **Lexer**: Tokenizes input into tokens (numbers, identifiers, operators, etc.) +- **Parser**: Builds Abstract Syntax Tree (AST) from tokens, translating operators to combinator calls +- **Interpreter**: Executes AST with scope management and combinator function calls + +### 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 +- **Combinator Foundation**: All operations implemented as function calls +- **Error Handling**: Comprehensive error reporting for parsing and execution + +## Recent Fixes + +### ✅ Combinator Foundation Implementation (Latest) +- **Issue**: Parser ambiguity between function application and operator expressions +- **Solution**: Implemented comprehensive combinator foundation +- **Status**: ✅ Completed - All operators now translate to combinator function calls +- **Impact**: Eliminated parsing ambiguity while preserving syntax + +### ✅ Standard Library Function Naming Conflicts +- **Issue**: Test functions using names that conflict with standard library combinators +- **Solution**: Renamed test functions to avoid conflicts (e.g., `add` → `add_func`) +- **Status**: ✅ Resolved - All tests now use unique function names + +### ✅ Parser Ambiguity with Unary Minus Arguments +- **Issue**: `filter @isPositive -3` was incorrectly parsed as binary operation +- **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 + +### ✅ 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 + +### ✅ IO Operation Parsing +- **Issue**: IO operations not parsed correctly at top level +- **Solution**: Moved IO parsing to proper precedence level +- **Status**: ✅ Resolved + +### ✅ Decimal Number Support +- **Issue**: Decimal numbers not handled correctly +- **Solution**: Updated lexer and interpreter to use `parseFloat()` +- **Status**: ✅ Resolved + +## Known Issues + +### 🔄 Recursive Function Support +- **Issue**: Functions cannot call themselves recursively +- **Example**: `factorial : n -> when n is 0 then 1 _ then n * factorial (n - 1);` fails +- **Root Cause**: Function not available in global scope when body is evaluated +- **Status**: 🔄 In Progress - Implementing forward declaration pattern +- **Impact**: Recursive algorithms cannot be implemented + +### 🔄 When Expression Pattern Parsing +- **Issue**: When expressions only support basic patterns (identifiers, numbers, strings, wildcards) +- **Example**: `when x is < 0 then "negative" _ then "non-negative"` fails +- **Root Cause**: Parser not handling comparison operators in patterns +- **Status**: 🔄 In Progress - Extending pattern parsing +- **Impact**: Limited pattern matching capabilities + +### 🔄 Dot Notation for Table Access +- **Issue**: Table access only supports bracket notation +- **Example**: `table.property` fails to parse +- **Root Cause**: Parser not handling dot notation +- **Status**: 🔄 In Progress - Adding dot notation support +- **Impact**: Less convenient table access syntax + +### 🔄 Multi-parameter Case Expressions +- **Issue**: Multi-parameter case expressions not parsed correctly +- **Example**: `when x y is 0 0 then "both zero" _ _ then "not both zero"` fails +- **Root Cause**: Parser not handling multiple parameters in case expressions +- **Status**: 🔄 In Progress - Extending case expression parsing +- **Impact**: Limited pattern matching with multiple values + +### 🔄 When Expression Parsing Precedence +- **Issue**: When expressions not parsed correctly in all contexts +- **Example**: Some when expressions fail with "Unexpected token in parsePrimary: WHEN" +- **Root Cause**: Parser precedence not handling when expressions properly +- **Status**: 🔄 In Progress - Adjusting parser precedence +- **Impact**: When expressions may fail in certain contexts + +## Development + +### File Structure +``` +. +├── lang.js # Main implementation with combinator foundation +├── parser.js # Parser with operator-to-combinator translation +├── lexer.js # Lexical analyzer +├── 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 +├── COMBINATORS.md # Combinator foundation documentation +└── README.md # This file +``` + +### Debugging +Enable debug mode by setting `DEBUG=true`: +```bash +DEBUG=true node lang.js script.txt +``` -## Language Design Principles +## Combinator Foundation -- **Simplicity**: Minimal syntax for maximum clarity -- **Immutability**: Variables cannot be reassigned -- **Functional**: Functions are first-class values with composition support -- **Pattern-oriented**: Pattern matching as a core feature -- **Recursive**: Support for recursive function calls in function bodies -- **Grouped**: Parentheses support for complex arithmetic expressions -- **Expressive**: Rich set of arithmetic, comparison, and logical operators -- **IO-aware**: Built-in input/output operations with clear impurity markers -- **Educational**: Designed to teach language implementation concepts +The language is built on a combinator foundation where all operations are implemented as function calls: -## Limitations +### Internal Translation +```javascript +// x - y becomes internally: +subtract(x, y) -This is a learning language with intentional limitations: -- Complex nested function calls (e.g., `add double 3 square 2`) are ambiguous without explicit grouping -- There's one known issue with function calls inside assertions (e.g., ..assert add 3 4 = 7), which is a parsing edge case. Workaround: use parentheses around function calls in assertions (e.g., ..assert (add 3 4) = 7) -- No data structures beyond numbers and strings -- No error handling beyond basic validation -- No modules or imports -- IO operations are synchronous and block execution +// filter @isPositive -3 becomes internally: +filter(isPositive, negate(3)) -## Future Enhancements +// x + y becomes internally: +add(x, y) -Planned features for future versions: -- Ambiguous function call detection and error reporting -- Lists and data structures -- Error handling -- Modules and imports -- Performance optimizations +// true and false becomes internally: +logicalAnd(true, false) +``` -## Implementation Details +### Benefits +- **Eliminates Parsing Ambiguity**: Every operation is a function call +- **Preserves Syntax**: Zero breaking changes to existing code +- **Functional Foundation**: Everything is a function under the hood +- **Extensible**: Easy to add new combinators and patterns +- **Consistent Semantics**: All operations follow the same pattern -The language is implemented in JavaScript with three main components: +For detailed information about the combinator foundation, see [COMBINATORS.md](COMBINATORS.md). -1. **Lexer** (`lexer()`): Converts source code to tokens -2. **Parser** (`parser()`): Builds AST from tokens -3. **Interpreter** (`interpreter()`): Executes AST +## Contributing -Each component is designed to be modular and extensible for adding new language features. \ No newline at end of file +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 +5. Follow the combinator foundation approach for new operations \ No newline at end of file |