Global

Logs debug error messages to console when DEBUG environment variable is set. Provides verbose error output during development while remaining silent in production. Debug functions are gated by the DEBUG environment variable, allowing for verbose output during development and silent operation in production. This approach makes it easy to trace execution and diagnose issues without cluttering normal output. This function is particularly useful for debugging parsing and evaluation errors, providing detailed context about where and why errors occur in the language execution pipeline.

Logs debug messages to console when DEBUG environment variable is set. Provides verbose output during development while remaining silent in production. Debug functions are gated by the DEBUG environment variable, allowing for verbose output during development and silent operation in production. This approach makes it easy to trace execution and diagnose issues without cluttering normal output. This function is essential for debugging the combinator-based architecture, allowing developers to trace how operators are translated to function calls and how the interpreter executes these calls through the standard library. The function is designed to be lightweight and safe to call frequently, making it suitable for tracing execution flow through nested expressions and function applications.

Main entry point for file execution. Handles the complete language pipeline: file reading, lexical analysis, parsing, and interpretation. This function orchestrates the entire language execution process: 1. Reads the source file using cross-platform I/O utilities 2. Tokenizes the source code using the lexer 3. Parses tokens into an AST using the combinator-based parser 4. Interprets the AST using the combinator-based interpreter The function provides comprehensive error handling and debug output at each stage for transparency and troubleshooting. It also manages the call stack tracker to provide execution statistics and detect potential issues. Supports both synchronous and asynchronous execution, with proper error handling and process exit codes. This function demonstrates the complete combinator-based architecture in action, showing how source code is transformed through each stage of the language pipeline. The function enforces the .txt file extension requirement and provides detailed error reporting with call stack statistics to help developers understand execution behavior and diagnose issues.

Injects higher-order functions and combinator functions into the interpreter's global scope. These functions provide functional programming utilities and implement the combinator foundation that reduces parsing ambiguity by translating all operations to function calls. The standard library includes: - Higher-order functions (map, compose, pipe, apply, filter, reduce, fold, curry) - Arithmetic combinators (add, subtract, multiply, divide, modulo, power, negate) - Comparison combinators (equals, notEquals, lessThan, greaterThan, lessEqual, greaterEqual) - Logical combinators (logicalAnd, logicalOr, logicalXor, logicalNot) - Enhanced combinators (identity, constant, flip, on, both, either) This approach ensures that user code can access these functions as if they were built-in, without special syntax or reserved keywords. The combinator foundation allows the parser to translate all operators to function calls, eliminating ambiguity while preserving syntax. Functions are written to check argument types at runtime since the language is dynamically typed and does not enforce arity or types at parse time. The combinator functions are designed to work seamlessly with the parser's operator translation, providing a consistent and extensible foundation for all language operations. The standard library is the foundation of the combinator-based architecture. Each function is designed to support partial application, enabling currying patterns and function composition. This design choice enables functional programming patterns while maintaining simplicity and consistency across all operations. Error handling is implemented at the function level, with clear error messages that help users understand what went wrong and how to fix it. This includes type checking for function arguments and validation of input data.

Evaluates an AST by walking through each node and performing the corresponding operations. Manages scope, handles function calls, and supports both synchronous and asynchronous operations. The interpreter implements a combinator-based architecture where all operations are executed through function calls to standard library combinators. This design reduces parsing ambiguity while preserving intuitive syntax. The parser translates all operators (+, -, *, /, etc.) into FunctionCall nodes that reference combinator functions, ensuring consistent semantics across all operations. Key architectural features: - Combinator Foundation: All operations are function calls to standard library combinators - Scope Management: Prototypal inheritance for variable lookup and function definitions - Forward Declaration: Recursive functions are supported through placeholder creation - Error Handling: Comprehensive error detection and reporting with call stack tracking - Debug Support: Optional debug mode for development and troubleshooting - IO Operations: Support for input/output operations through environment interface The interpreter processes legacy operator expressions (PlusExpression, MinusExpression, etc.) for backward compatibility, but the parser now generates FunctionCall nodes for all operators, which are handled by the standard library combinator functions. This ensures that all operations follow the same execution model and can be extended by adding new combinator functions to the standard library. The interpreter uses a global scope for variable storage and function definitions. Each function call creates a new scope (using prototypal inheritance) to implement lexical scoping. Immutability is enforced by preventing reassignment in the global scope. The interpreter is split into three functions: evalNode (global), localEvalNodeWithScope (for function bodies), and localEvalNode (for internal recursion). This separation allows for correct scope handling and easier debugging. Recursive function support is implemented using a forward declaration pattern: a placeholder function is created in the global scope before evaluation, allowing the function body to reference itself during evaluation. The combinator foundation ensures that all operations are executed through function calls, providing a consistent and extensible execution model. This approach enables abstractions and reduces the need for special handling of different operator types in the interpreter. The interpreter supports both synchronous and asynchronous operations. IO operations like input and output can return Promises, allowing for non-blocking execution when interacting with external systems or user input.

The lexer performs lexical analysis by converting source code into a stream of tokens. Each token represents a meaningful unit of the language syntax, such as identifiers, literals, operators, and keywords. The lexer implements a character-by-character scanning approach with lookahead for multi-character tokens. It maintains line and column information for accurate error reporting and debugging. Key features: - Handles whitespace and comments (single-line and multi-line) - Recognizes all language constructs including operators, keywords, and literals - Supports string literals with escape sequences - Provides detailed position information for error reporting - Cross-platform compatibility (Node.js, Bun, browser) - Supports function composition with 'via' keyword - Handles function references with '@' operator The lexer is designed to be robust and provide clear error messages for malformed input, making it easier to debug syntax errors in user code. It supports the combinator-based architecture by recognizing all operators and special tokens needed for function composition and application. The lexer is the first step in the language processing pipeline and must correctly identify all tokens that the parser will translate into function calls. This includes operators that will become combinator function calls, function references that enable higher-order programming, and special keywords that support the functional programming paradigm. The lexer uses a state machine approach where each character type triggers different parsing strategies. This design enables efficient tokenization while maintaining clear separation of concerns for different token types. The character-by-character approach allows for precise error reporting and supports multi-character tokens like operators and string literals with escape sequences. Error handling is designed to provide meaningful feedback by including line and column information in error messages. This enables users to quickly locate and fix syntax errors in their code.

Processes command line arguments and executes the specified file. Provides helpful error messages for incorrect usage. The language is designed for file execution only (no REPL), so the CLI enforces this usage and provides helpful error messages for incorrect invocation. The function validates that exactly one file path is provided and that the file has the correct .txt extension. Exits with appropriate error codes for different failure scenarios.

The parser implements a combinator-based architecture where all operators are translated to function calls to standard library combinators. This reduces parsing ambiguity while preserving the original syntax. The parser uses a recursive descent approach with proper operator precedence handling. Each operator expression (e.g., x + y) is translated to a FunctionCall node (e.g., add(x, y)) that will be executed by the interpreter using the corresponding combinator function. Key architectural decisions: - All operators become FunctionCall nodes to eliminate ambiguity - Operator precedence is handled through recursive parsing functions - Function calls are detected by looking for identifiers followed by expressions - When expressions and case patterns are parsed with special handling - Table literals and access are parsed as structured data - Function composition uses 'via' keyword with right-associative precedence - Function application uses juxtaposition with left-associative precedence The parser maintains a current token index and advances through the token stream, building the AST bottom-up from primary expressions to logical expressions. This approach ensures that all operations are consistently represented as function calls, enabling the interpreter to use the combinator foundation for execution. This design choice reduces the need for special operator handling in the interpreter and enables abstractions through the combinator foundation. All operations become function calls, providing a consistent and extensible execution model that can be enhanced by adding new combinator functions. The parser implements a top-down recursive descent strategy where each parsing function handles a specific precedence level. This approach ensures that operator precedence is correctly enforced while maintaining clear separation of concerns for different language constructs. Error handling is designed to provide meaningful feedback by including context about what was expected and what was found. This enables users to quickly identify and fix parsing errors in their code.

Handles file reading across different platforms (Node.js, Bun, browser) with appropriate fallbacks for each environment. This function is essential for the language's file execution model where scripts are loaded from .txt files. The function prioritizes ES modules compatibility by using dynamic import, but falls back to require for older Node.js versions. Browser environments are not supported for file I/O operations. This cross-platform approach ensures the language can run in various JavaScript environments while maintaining consistent behavior. The file reading capability enables the language to execute scripts from files, supporting the development workflow where tests and examples are stored as .txt files.

Parses and executes a script using the combinator-based language. This function orchestrates the entire execution pipeline from source code to final result. The function performs the following steps: 1. Tokenize the source code using the lexer 2. Parse the tokens into an AST using the parser 3. Evaluate the AST using the interpreter 4. Return the final result This is the primary interface for executing scripts in the language. It handles the parsing and evaluation pipeline, providing a simple interface for users to run their code. The function supports both synchronous and asynchronous execution. When the script contains IO operations that return Promises, the function will return a Promise that resolves to the final result. This enables non-blocking execution for interactive programs. Error handling is comprehensive, with errors from any stage of the pipeline (lexing, parsing, or evaluation) being caught and re-thrown with appropriate context. This ensures that users get meaningful error messages that help them identify and fix issues in their code. The function is designed to be stateless, with each call creating a fresh interpreter instance. This ensures that scripts don't interfere with each other and enables safe concurrent execution of multiple scripts.