diff options
Diffstat (limited to 'js/scripting-lang/README.md')
| -rw-r--r-- | js/scripting-lang/README.md | 169 |
1 files changed, 130 insertions, 39 deletions
diff --git a/js/scripting-lang/README.md b/js/scripting-lang/README.md index 73ccbf1..08334a4 100644 --- a/js/scripting-lang/README.md +++ b/js/scripting-lang/README.md @@ -1,6 +1,6 @@ # Simple Scripting Language -A functional programming language with immutable variables, first-class functions, and pattern matching. +A functional programming language with immutable variables, first-class functions, and pattern matching, built on a combinator-based foundation. ## Features @@ -10,10 +10,29 @@ A functional programming language with immutable variables, first-class function - **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 ### Basic Operations @@ -55,17 +74,17 @@ table : {1, 2, 3, key: "value"}; /* Table access */ first : table[1]; -value : table.key; -nested : table.key.subkey; +value : table.key; /* Coming soon */ +nested : table.key.subkey; /* Coming soon */ ``` ### Pattern Matching ``` /* Case expression */ -result : case x of - 1 : "one" - 2 : "two" - _ : "other"; +result : when x is + 1 then "one" + 2 then "two" + _ then "other"; ``` ### IO Operations @@ -109,22 +128,27 @@ 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 +- `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 +- `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 @@ -134,25 +158,39 @@ Test combinations of multiple features: # 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 ``` ## Implementation Details ### Architecture - **Lexer**: Tokenizes input into tokens (numbers, identifiers, operators, etc.) -- **Parser**: Builds Abstract Syntax Tree (AST) from tokens -- **Interpreter**: Executes AST with scope management +- **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 -### ✅ 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 +### ✅ 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 @@ -175,25 +213,49 @@ node lang.js tests/integration_01_basic_features.txt ## Known Issues -### 🔄 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)` - -### 🔄 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 +### 🔄 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 -├── test.txt # Comprehensive test file +├── 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 @@ -202,7 +264,7 @@ node lang.js tests/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 +├── COMBINATORS.md # Combinator foundation documentation └── README.md # This file ``` @@ -212,9 +274,38 @@ Enable debug mode by setting `DEBUG=true`: DEBUG=true node lang.js script.txt ``` +## Combinator Foundation + +The language is built on a combinator foundation where all operations are implemented as function calls: + +### Internal Translation +```javascript +// x - y becomes internally: +subtract(x, y) + +// filter @isPositive -3 becomes internally: +filter(isPositive, negate(3)) + +// x + y becomes internally: +add(x, y) + +// true and false becomes internally: +logicalAnd(true, false) +``` + +### 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 + +For detailed information about the combinator foundation, see [COMBINATORS.md](COMBINATORS.md). + ## Contributing 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 +4. Run the full test suite before submitting changes +5. Follow the combinator foundation approach for new operations \ No newline at end of file |