Using the REPL

Relevant source files

The following files were used as context for generating this wiki page:

• REPL/Program.cs
• Jurassic/ScriptEngine.cs
• Jurassic/Library/FirebugConsole.cs
• [Unit Tests/Core/DocumentationSamples.cs](https://github.com/zhgabor/jurassic/blob/HEAD/Unit Tests/Core/DocumentationSamples.cs)
• Jurassic/Compiler/Parser.cs
• Jurassic/Compiler/Lexer.cs
• Jurassic/Compiler/Compiler.cs

The Jurassic REPL (Read-Eval-Print Loop) is a command-line utility that provides an interactive console for executing JavaScript code. It is built upon the core ScriptEngine and serves as a powerful tool for developers to quickly test JavaScript snippets, explore the engine's features, and debug compilation processes. The REPL supports standard JavaScript evaluation, multi-line input, and a set of special commands for controlling the environment and inspecting the internal workings of the compiler.

This document details the architecture, functionality, and usage of the Jurassic REPL, based on its implementation in REPL/Program.cs.

Core Architecture

The REPL application's architecture is centered around the Jurassic.ScriptEngine. The Main method in REPL/Program.cs initializes an engine instance and enters a loop to process user input. For console output capabilities like console.log(), it attaches an instance of FirebugConsole.

The following diagram illustrates the main components and their interactions within the REPL application.

The REPL Loop

The core of the REPL is an infinite loop that reads lines from the console, evaluates them as JavaScript, and prints the result or any errors that occur.

Input Processing Flow

The REPL can handle both single-line and multi-line JavaScript statements. It accumulates lines until a complete statement can be parsed and executed.

This flowchart shows the logic for processing user input within the REPL.

Evaluation

For each complete code block, the REPL uses engine.Evaluate() to execute the code. The result of the evaluation is then displayed on the console. If the result is undefined, nothing is printed.

// REPL/Program.cs:88-95
try
{
    // Evaluate the javascript.
    var result = engine.Evaluate(source.ToString());
    if (result != Undefined.Value)
        Console.WriteLine(result);
}
catch (JavaScriptException ex)
{
    Console.WriteLine(ex.Message);
}

Sources: REPL/Program.cs:88-95, Unit Tests/Core/DocumentationSamples.cs:17-20

Special Commands

The REPL supports several special commands, prefixed with a dot (.), to control the session and inspect the compilation process. These are handled within a switch statement in Program.cs.

Sources: REPL/Program.cs:46-85

Command	Description
.help	Displays a list of available special commands.
.exit	Exits the REPL application.
.dump ast	Dumps the Abstract Syntax Tree (AST) for the last entered code block. This is useful for understanding how the Parser interprets the code.
.dump tokens	Dumps the lexical tokens for the last entered code block, showing the output of the Lexer.
.dump il	Dumps the generated IL (Intermediate Language) for the last entered code block.

Dumping Internals

The .dump commands provide insight into the Jurassic engine's compilation pipeline.

1. .dump tokens: Shows the raw tokens generated by the Lexer.
2. .dump ast: Displays the Abstract Syntax Tree generated by the Parser.
3. .dump il: Shows the low-level .NET Intermediate Language generated by the Compiler.

This sequence diagram illustrates the process for the .dump ast command.

Error Handling

The REPL is designed to be resilient. Any JavaScriptException or other runtime error that occurs during evaluation is caught, and its message is printed to the console. The loop then continues, allowing the user to enter more code. This prevents a single faulty script from terminating the entire interactive session.

// REPL/Program.cs:96-104
catch (Exception ex)
{
    Console.ForegroundColor = ConsoleColor.Red;
    Console.WriteLine(ex.Message);
    Console.ResetColor();
}

// Clear the source buffer.
source.Clear();

This try-catch block ensures that the REPL remains active even after an error, clearing the buffer and preparing for the next input.

Sources: REPL/Program.cs:88-106

Conclusion

The Jurassic REPL is a simple yet effective developer tool for interacting with the JavaScript engine. It leverages the core ScriptEngine for evaluation and provides additional commands for debugging and inspecting the compilation process from tokenization to IL generation. Its robust error handling and multi-line input support make it a practical utility for testing and exploring JavaScript execution within the .NET environment provided by Jurassic.