diff options
Diffstat (limited to 'js/scripting-lang/WHAT-IS-THIS.md')
| -rw-r--r-- | js/scripting-lang/WHAT-IS-THIS.md | 289 |
1 files changed, 0 insertions, 289 deletions
diff --git a/js/scripting-lang/WHAT-IS-THIS.md b/js/scripting-lang/WHAT-IS-THIS.md deleted file mode 100644 index 8949920..0000000 --- a/js/scripting-lang/WHAT-IS-THIS.md +++ /dev/null @@ -1,289 +0,0 @@ -# What is this project? - -## Overview -A **combinator-based functional programming language** that eliminates parsing ambiguity by translating all operations into function calls. Every operator becomes a combinator function call under the hood, creating a consistent and extensible language architecture. - -## Core Architecture -- **Combinator Foundation**: All operations translate to function calls (`x + y` → `add(x, y)`) -- **Zero Ambiguity**: Every expression has exactly one interpretation -- **Functional Semantics**: Everything is a function or function application -- **Juxtaposition-Based Application**: Functions applied by placing arguments next to them (`f x`) - -## Key Files -- **`lang.js`** - Main interpreter with standard library combinator functions -- **`parser.js`** - AST generation with operator-to-function translation -- **`lexer.js`** - Tokenization with support for all operators including `@` -- **`tests/`** - Comprehensive test suite (18 tests total) -- **`scratch_tests/`** - Rapid prototyping and debugging tests - -## Language Features - -### ✅ Working Features (13/14) -1. **Function References**: `@functionName` returns function reference -2. **Function Application**: `f x y` → `apply(apply(f, x), y)` -3. **Function Definitions**: `f : x y -> x + y` (arrow syntax) -4. **Pattern Matching**: `when x is 1 then "one" _ then "other"` -5. **Tables**: `{1, 2, name: "value"}` (Lua-style) -6. **IO Operations**: `..in`, `..out`, `..assert` -7. **Standard Library**: `map`, `compose`, `pipe`, `reduce`, `filter`, etc. -8. **Operator Precedence**: All arithmetic and logical operators work correctly -9. **Comments**: `/* C-style comments */` -10. **Literals**: Numbers, strings, booleans -11. **Assignment**: `x : 5` (immutable by default) -12. **Debug System**: `DEBUG=1` for detailed output -13. **Testing Framework**: Progressive testing approach - -### 🔧 Partially Working (1/14) -1. **Pattern Matching (when expressions)** - Parsing issues being resolved - -## Current Status - -### ✅ Recently Completed -- **@ Operator**: Function reference syntax working perfectly -- **Standard Library**: All higher-order functions working with @ syntax -- **Precedence Issues**: All operator precedence issues resolved -- **Partial Application**: Fixed `reduce`, `fold`, `curry` functions - -### 🔧 Active Issues -- **Case Expression Parsing**: Fix "Unexpected token in parsePrimary: THEN" errors -- **Test Suite**: Get all tests passing (currently 8/18) - -### 📊 Test Results -- **Passing**: 8/18 tests (all core features working) -- **Failing**: 10/18 tests (due to case expression parsing) -- **Architecture**: Working correctly -- **Function Composition**: ✅ Complete and working - -## Language Syntax Examples - -### Basic Operations -```javascript -/* Arithmetic with combinator translation */ -x : 5; -y : 3; -result : x + y; // becomes add(x, y) internally - -/* Function definition and application */ -double : x -> x * 2; -result : double 5; // becomes apply(double, 5) internally - -/* Function references */ -ref : @double; // function reference -result : ref 5; // call referenced function -``` - -### Pattern Matching -```javascript -/* Case expressions with wildcards */ -grade : score -> when score is - 90 then "A" - 80 then "B" - 70 then "C" - _ then "F"; - -/* Multiple patterns */ -result : when x y is - 1 2 then "one two" - 3 4 then "three four" - _ _ then "other"; -``` - -### Tables and Data Structures -```javascript -/* Mixed array and key-value syntax */ -person : {name: "Alice", age: 30}; -numbers : {1, 2, 3, 4, 5}; - -/* Access with dot notation */ -name : person.name; // "Alice" -first : numbers.1; // 1 -``` - -### Standard Library Usage -```javascript -/* Higher-order functions with @ syntax */ -double_func : x -> x * 2; -mapped : map @double_func 5; // map(double_func, 5) -composed : compose @double_func @square_func 3; // compose(double_func, square_func)(3) -reduced : reduce @add_func 0 5; // reduce(add_func, 0, 5) -``` - -## Development Workflow - -### Testing Strategy -- **Scratch Tests**: `scratch_tests/` for rapid prototyping and debugging -- **Unit Tests**: `tests/` for comprehensive feature coverage -- **Integration Tests**: `tests/integration_*.txt` for feature combinations -- **Promote**: scratch → unit when stable - -### Debugging -```bash -# Enable debug mode for detailed output -DEBUG=1 node lang.js script.txt - -# Run all tests -./run_tests.sh - -# Run individual test -node lang.js tests/01_lexer_basic.txt - -# Run scratch test -node lang.js scratch_tests/test_debug_issue.txt -``` - -## Technical Implementation - -### Parser Architecture -**Precedence Chain**: -``` -parseLogicalExpression() → parseExpression() → parseTerm() → parseApplication() → parseComposition() → parseFactor() → parsePrimary() -``` - -**Operator Translation**: -```javascript -// Arithmetic -x + y → add(x, y) -x - y → subtract(x, y) -x * y → multiply(x, y) - -// Comparison -x = y → equals(x, y) -x > y → greaterThan(x, y) - -// Logical -x and y → logicalAnd(x, y) -not x → logicalNot(x) - -// Function application -f x → apply(f, x) -``` - -### Standard Library Combinators -- **Arithmetic**: `add`, `subtract`, `multiply`, `divide`, `negate` -- **Comparison**: `equals`, `greaterThan`, `lessThan`, etc. -- **Logical**: `logicalAnd`, `logicalOr`, `logicalNot` -- **Higher-Order**: `map`, `compose`, `pipe`, `apply`, `filter` -- **Reduction**: `reduce`, `fold` with partial application -- **Utility**: `curry`, `identity`, `constant`, `flip` - -### Scope Management -- **Global Scope**: Standard library and user functions -- **Local Scopes**: Function parameters with prototypal inheritance -- **Immutability**: Variables cannot be reassigned -- **Lexical Scoping**: Functions create their own scope - -## Key Design Decisions - -### 1. Combinator Foundation -- **Why**: Eliminates parsing ambiguity entirely -- **How**: All operators translate to function calls -- **Benefit**: Zero ambiguity, consistent patterns - -### 2. Juxtaposition-Based Application -- **Why**: Natural, readable syntax -- **How**: Parser detects function application through juxtaposition -- **Benefit**: Intuitive function calls without parentheses - -### 3. Function References (@ operator) -- **Why**: Enable higher-order programming patterns -- **How**: `@functionName` returns function object -- **Benefit**: Powerful abstractions and function composition - -### 4. Immutable by Default -- **Why**: Prevents bugs and enables functional programming -- **How**: Interpreter enforces immutability in global scope -- **Benefit**: Predictable behavior and easier reasoning - -## Common Patterns - -### Function Application Chain -```javascript -f x y z → apply(apply(apply(f, x), y), z) -``` - -### Partial Application -```javascript -reduce @add_func 0 5 → apply(apply(apply(reduce, @add_func), 0), 5) -``` - -### Pattern Matching -```javascript -when value is - pattern1 then result1 - pattern2 then result2 - _ then defaultResult -``` - -### Table Construction -```javascript -{key1: value1, key2: value2} // Key-value pairs -{1, 2, 3, 4, 5} // Array-like -``` - -## Error Handling - -### Common Error Types -- **Parser Errors**: "Unexpected token in parsePrimary: THEN" -- **Type Errors**: "apply: first argument must be a function" -- **Undefined Variables**: "Variable x is not defined" -- **Immutable Reassignment**: "Cannot reassign immutable variable" - -### Debug Information -- **Token Stream**: Shows lexer output -- **AST Structure**: Shows parser output -- **Call Stack**: Tracks function calls and recursion -- **Scope Information**: Shows variable bindings - -## Future Enhancements - -### Planned Features -1. **Enhanced Pattern Matching**: Fix current parsing issues -2. **I/O Enhancements**: `..listen` and `..emit` functions -3. **Performance Optimizations**: Parser and interpreter improvements -4. **Additional Standard Library**: More higher-order functions - -### Architecture Improvements -1. **Better Error Messages**: More specific error reporting -2. **Performance Monitoring**: Built-in performance metrics -3. **Module System**: Support for importing/exporting -4. **REPL**: Interactive development environment - -## Documentation - -### Design Documents -- **[design/README.md](design/README.md)** - Main design documentation entry point -- **[design/PROJECT_ROADMAP.md](design/PROJECT_ROADMAP.md)** - Current status and next steps -- **[design/COMBINATORS.md](design/COMBINATORS.md)** - Combinator foundation explanation -- **[design/ARCHITECTURE.md](design/ARCHITECTURE.md)** - Complete system architecture overview - -### Implementation Guides -- **[design/implementation/IMPLEMENTATION_GUIDE.md](design/implementation/IMPLEMENTATION_GUIDE.md)** - Current implementation guide -- **[design/implementation/COMPLETED_FEATURES.md](design/implementation/COMPLETED_FEATURES.md)** - Summary of completed features - -## Quick Reference - -### Key Commands -```bash -# Run script -node lang.js script.txt - -# Debug mode -DEBUG=1 node lang.js script.txt - -# Run all tests -./run_tests.sh - -# Run specific test -node lang.js tests/01_lexer_basic.txt -``` - -### Current Focus -- **Immediate Priority**: Fix case expression parsing issues -- **Goal**: Get all 18 tests passing -- **Architecture**: Solid foundation, ready for enhancements -- **Status**: 13/14 core features working correctly - ---- - -**Last Updated**: Current development focus is case expression parsing -**Status**: Active development with strong foundation (8/18 tests passing) \ No newline at end of file |