repl.md

Implementing a Read–eval–print loop (REPL) in the PerlOnJava compiler can be a powerful tool for interacting with Perl code in real-time. To create a robust REPL, incorporating the features suggested by Wikipedia, we need to leverage both Java libraries and Perl runtime capabilities. Here's a strategy for how to approach this:

Key Features to Implement in the PerlOnJava REPL

1. History of Inputs and Outputs:

   • Java Library: Use a library like JLine (used in Groovy’s REPL and others) for handling command-line input with support for history, line editing, and tab-completion.
   • Store the results of each evaluation in a list (List<String> in Java) or use global Perl variables like $_, $__, $___ to refer to recent results, following the Lisp-style *, **, ***.

2. Variables for Input Expressions and Results:

   • Create an internal mechanism to store each result in a sequence, such as a map of previous expressions (input_n) and their results (output_n).
   • In Perl, use the special variable syntax ($__, $___ for result history), and store the last evaluated expressions as well.

   Map<String, RuntimeScalar> previousResults = new LinkedHashMap<>();
   previousResults.put("_1", result);  // last result
   previousResults.put("_2", previousResult); // second last result

3. Error Handling with Levels of REPLs:

   • In the event of an error, start a new REPL level. If an exception occurs, push the current context onto a stack and launch a new REPL session.
   • Java Exception Handling: Implement an exception handling mechanism where, if an error occurs, the stack is unwound, and the user can interact with the context where the error happened.

   try {
       eval(input);
   } catch (RuntimeException e) {
       pushREPLLevel();
       System.out.println("Error: " + e.getMessage());
       startREPL();  // Start nested REPL to allow debugging
   }

4. Restarts on Errors:

   • Provide "restart" options using exception handling or state restoration features. This allows the user to either continue after an error, exit the nested REPL, or go back to the top level.
   • Use a try-catch-finally block to control the restart behavior, and maintain a stack of REPL levels.

5. Input Editing and Context-Specific Completion:

   • JLine can provide tab-completion for variables, functions, and symbols, similar to how the Python or Bash REPL offers completions. This can be integrated with the Perl symbol table to suggest variable names or function names.

6. Mouse-Sensitive Input and Output:

   • This feature is advanced and depends on the user interface. If the REPL is run in a terminal, libraries like JLine can be extended to detect mouse inputs, but for a standard text-based REPL, it is less common.

7. Help and Documentation:

   • Integrate basic help commands within the REPL (help, ?). This can be mapped to look up Perl documentation (perldoc) or Java documentation for the built-in REPL commands.

   if (input.equals("help")) {
       System.out.println("Available commands: help, exit, history...");
   }

8. Reader Control Variables:

   • Implement variables like *read-base* in Lisp to control how the input is read. For example, adding settings like $*base = 16; to change the base of number parsing.
   • A configuration object (REPLSettings) can be used to store these settings and be referenced during evaluation.

   public class REPLSettings {
       private int base = 10;  // default base
       public int getBase() { return base; }
       public void setBase(int base) { this.base = base; }
   }

High-Level Plan for REPL Implementation

1. Core Structure:

   • REPL Loop: A continuous loop that reads user input, evaluates it, prints the result, and handles exceptions.
   • State Management: Maintain a stack of states (Stack<REPLState>) to handle nested REPL levels when exceptions occur.

   while (true) {
       String input = reader.readLine("perl> ");
       try {
           Object result = eval(input);
           System.out.println(result);
       } catch (RuntimeException e) {
           System.out.println("Error: " + e.getMessage());
           pushREPLLevel();
       }
   }

2. Evaluation and Execution:

   • Use the Perl interpreter backend to evaluate Perl code dynamically using the eval function.
   • Wrap the Perl interpreter or runtime logic in Java, allowing for dynamic execution of Perl expressions.

   public Object eval(String input) {
       // Parse and evaluate Perl expression
       RuntimeScalar result = perlInterpreter.eval(input);
       return result;
   }

3. Error Handling and Nested REPL:

   • Capture errors and start a new REPL level if necessary. Maintain a stack of contexts to allow users to fix errors and resume.

4. Input Editing and History:

   • Use JLine or a similar library to handle command-line input, providing features like history navigation (up/down arrows) and tab-completion for Perl symbols.

   ConsoleReader reader = new ConsoleReader();
   reader.setHistory(new FileHistory(new File("perl_repl_history")));

5. Help Commands and Special Variables:

   • Implement special REPL commands such as help, history, quit, and exit, and make sure they are documented and accessible within the REPL.
   • Maintain a list of recent expressions and results, making them accessible as Perl variables (e.g., $_ for the last result).

Java Libraries to Consider:

• JLine: For line editing, history, and tab-completion.
• Apache Commons Lang: For utilities like reflection, if needed.
• Groovy Shell or BeanShell: Java libraries that could serve as inspiration for implementing a custom REPL.