From d7677d7941d5bbdc8a4ec4ce739f46514633d9aa Mon Sep 17 00:00:00 2001
From: retoor <retoor@molodetz.nl>
Date: Fri, 5 Dec 2025 12:36:51 +0100
Subject: [PATCH] Updated Readme

---
 README.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 93 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index f0bab8a..9239182 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,20 @@ make
 
 ## Usage
 
+Run a Java file:
+
+```bash
+./rava file.java
+./rava file.java ClassName
+./rava file.java ClassName method
+```
+
+Start interactive REPL:
+
+```bash
+./rava
+```
+
 Example source code:
 
 ```java
@@ -68,6 +82,69 @@ Run all tests:
 make test
 ```
 
+## Interactive REPL
+
+Rava includes a full-featured interactive interpreter.
+
+```
+$ ./rava
+Rava 1.0 Interactive Interpreter
+Type "%help" for commands, "%quit" to exit
+
+>>> int x = 10;
+>>> int y = 20;
+>>> x + y
+30
+>>> int fib(int n) { if (n <= 1) return n; return fib(n-1) + fib(n-2); }
+Method 'fib' defined.
+>>> fib(10)
+55
+>>> class Point { public int x; public int y; public Point(int px, int py) { this.x = px; this.y = py; } }
+Class 'Point' defined.
+>>> Point p = new Point(3, 4);
+>>> p.x
+3
+>>> %whos
+Variable             Type            Value
+--------             ----            -----
+x                    int             10
+y                    int             20
+p                    Point           null
+>>> %quit
+```
+
+### REPL Features
+
+- Variable declarations with persistence across executions
+- Expression evaluation with automatic output
+- User-defined methods callable after definition
+- User-defined classes instantiable after definition
+- Array declarations
+- Multi-line input with brace/bracket/paren tracking
+- String methods and Math functions
+- Control flow statements (for, while, if/else, switch)
+
+### Magic Commands
+
+| Command    | Description                    |
+|------------|--------------------------------|
+| %help      | Show help for commands         |
+| %whos      | List all variables with types  |
+| %who       | List all variable names        |
+| %methods   | List session methods           |
+| %classes   | List session classes           |
+| %reset     | Clear all session state        |
+| %clear     | Clear screen                   |
+| %debug     | Toggle debug mode              |
+| %history   | Show input history             |
+| %quit      | Exit REPL                      |
+
+### REPL Tests
+
+```bash
+make test_repl
+```
+
 ## Performance
 
 Rava beats Python on all benchmarks.
@@ -113,14 +190,22 @@ rava/
 │   ├── runtime.h
 │   ├── runtime.c
 │   ├── nanbox.h
-│   ├── fastframe.h
-│   ├── fastframe.c
-│   ├── labeltable.h
-│   ├── labeltable.c
-│   ├── methodcache.h
-│   ├── methodcache.c
-│   ├── superinst.h
-│   └── superinst.c
+│   ├── fastframe.h/c
+│   ├── labeltable.h/c
+│   ├── methodcache.h/c
+│   ├── superinst.h/c
+│   └── gc/
+├── repl/
+│   ├── repl.h/c
+│   ├── repl_session.h/c
+│   ├── repl_input.h/c
+│   ├── repl_executor.h/c
+│   ├── repl_output.h/c
+│   ├── repl_commands.h/c
+│   ├── repl_history.h/c
+│   ├── repl_types.h
+│   ├── tests/
+│   └── examples/
 ├── tests/
 │   └── test_*.c
 ├── examples/