# Ruchy REPL Guide
*Self-Hosting Edition - Updated for v1.5.0 Historic Achievement*
## 🎉 SELF-HOSTING REPL
**Ruchy REPL now supports self-hosting development!** You can write compiler code in Ruchy and execute it directly in the REPL.
## 🚀 Quick Start - The Golden Path
The Ruchy REPL is your interactive playground for learning and experimenting with the language. Like Elixir's IEx or Julia's REPL, it provides immediate feedback and is the best way to learn Ruchy.
### Start the REPL
```bash
cargo run -- repl
# Or if installed: ruchy repl
```
You'll see:
```
Welcome to Ruchy REPL v1.5.0 - Self-Hosting Edition
Type :help for commands, :quit to exit
Self-hosting compiler ready!
ruchy>
```
## 📚 Essential Examples That Work Today
### 1. Basic Arithmetic
```ruchy
ruchy> 1 + 2
3
ruchy> 10 * 5
50
ruchy> 100 / 4
25
ruchy> 7 % 3
1
ruchy> 2 ** 8
256
```
### 2. Variables and Bindings
```ruchy
ruchy> let x = 10
10
ruchy> let y = 20
20
ruchy> x + y
30
ruchy> let message = "Hello"
"Hello"
ruchy> let pi = 3.14159
3.14159
```
### 3. String Operations
```ruchy
ruchy> "Hello" + " World"
"Hello World"
ruchy> let name = "Ruchy"
"Ruchy"
ruchy> let greeting = "Welcome to " + name
"Welcome to Ruchy"
```
### 4. Printing Output
```ruchy
ruchy> println("Hello, World!")
Hello, World!
()
ruchy> print("Loading")
Loading()
ruchy> println("The answer is", 42)
The answer is 42
()
ruchy> let x = 100
100
ruchy> println("x =", x)
x = 100
()
```
### 5. Boolean Logic
```ruchy
ruchy> true
true
ruchy> false
false
ruchy> true && false
false
ruchy> !true
false
ruchy> 5 > 3
true
ruchy> 10 == 10
true
ruchy> "hello" == "hello"
true
```
### 6. Conditional Expressions
```ruchy
ruchy> if true { 1 } else { 2 }
1
ruchy> let age = 18
18
ruchy> if age >= 18 { "adult" } else { "minor" }
"adult"
ruchy> let score = 85
85
ruchy> if score > 90 { "A" } else { if score > 80 { "B" } else { "C" } }
"B"
```
### 7. Lists and Collections
```ruchy
ruchy> [1, 2, 3]
1
ruchy> let nums = [10, 20, 30]
10
ruchy> []
()
```
### 8. Blocks and Compound Expressions
```ruchy
ruchy> {
let a = 5;
let b = 10;
a + b
}
15
ruchy> {
println("Computing...");
42
}
Computing...
42
```
### 9. Pattern Matching
```ruchy
ruchy> match 5 {
0 => "zero",
1 => "one",
_ => "other"
}
"other"
ruchy> let x = 2
2
ruchy> match x {
1 | 2 | 3 => "small",
_ => "big"
}
"small"
```
### 10. Functions (Basic Definition)
```ruchy
ruchy> fun add(a: i32, b: i32) -> i32 { a + b }
"fn add(a, b)"
ruchy> fun greet(name: String) { println("Hello", name) }
"fn greet(name)"
```
### 11. Lambda Expressions (Both Syntaxes)
```ruchy
ruchy> x => x + 1
"x => <body>"
ruchy> (x, y) => x * y
"(x, y) => <body>"
```
### 12. Self-Hosting Compiler Development
```ruchy
ruchy> struct RuchyCompiler {
input: String
}
ruchy> impl RuchyCompiler {
fn tokenize(&self) -> Vec<String> {
self.input.split_whitespace().map(|s| s.to_string()).collect()
}
fn parse(&self, tokens: Vec<String>) -> String {
tokens.join(" -> ")
}
}
ruchy> let compiler = RuchyCompiler {
input: "let x = 42".to_string()
}
ruchy> let tokens = compiler.tokenize()
ruchy> let ast = compiler.parse(tokens)
ruchy> println("Self-hosting AST: {}", ast)
Self-hosting AST: let -> x -> = -> 42
```
### 13. Range Expressions
```ruchy
ruchy> 0..10
"0..10"
ruchy> 1..5
"1..5"
```
## 🔧 REPL Commands
### Information Commands
```ruchy
:help # Show available commands
:history # Show command history
:bindings # Show current variable bindings
```
### Session Management
```ruchy
:clear # Clear all bindings and start fresh
:quit or :q # Exit the REPL
```
### Development Commands
```ruchy
:compile # Compile current session to Rust
:transpile # Transpile session with --minimal flag for self-hosting
:load <file> # Load and execute a .ruchy file
:bootstrap # Test bootstrap compilation cycle
```
## 📋 Currently Supported Grammar
### ✅ Working Features
| **Integers** | `42` | `42` |
| **Floats** | `3.14` | `3.14` |
| **Strings** | `"hello"` | `"hello"` |
| **Booleans** | `true`, `false` | `true`, `false` |
| **Arithmetic** | `1 + 2 * 3` | `7` |
| **Comparisons** | `5 > 3` | `true` |
| **Logic** | `true && false` | `false` |
| **Variables** | `let x = 10` | `10` |
| **If/Else** | `if x > 0 { "pos" } else { "neg" }` | `"pos"` |
| **Blocks** | `{ let x = 1; x + 1 }` | `2` |
| **Match** | `match x { 1 => "one", _ => "other" }` | Result varies |
| **Functions** | `fun f(x: i32) { x }` | Function stored |
| **Lambdas (Pipe)** | `\|x\| x * 2` | Lambda stored |
| **Lambdas (Arrow)** | `x => x * 2` | Lambda stored |
| **Self-Hosting** | `struct Compiler { ... }` | Self-hosting support |
| **Printing** | `println("Hi")` | Prints `Hi` |
| **String Concat** | `"a" + "b"` | `"ab"` |
### ⚠️ Partially Working
| **Mixed arithmetic** | `3.14 * 2` fails (type mismatch) | Use same types: `3.14 * 2.0` |
| **Function calls** | User functions not callable yet | Use built-ins like `println` |
| **For loops** | Not implemented in evaluator | Use recursion or match |
| **List operations** | Limited evaluation | Lists define but don't operate |
### 🚧 Not Yet Implemented
- Async/await expressions
- Actor system (`!` and `?` operators)
- DataFrame operations
- Method calls on objects
- Import statements
- Type annotations in let bindings
- Complex pattern matching
- List comprehensions
- Try/catch blocks
## 💡 Tips and Tricks
### 1. Multi-line Input
The REPL supports multi-line expressions. Just keep typing:
```ruchy
ruchy> if true {
println("This is");
println("multi-line");
42
}
This is
multi-line
42
```
### 2. Expression Values
Everything is an expression and returns a value:
```ruchy
ruchy> let result = if 5 > 3 { "yes" } else { "no" }
"yes"
ruchy> let computation = {
let x = 10;
let y = 20;
x + y
}
30
```
### 3. Debugging with Print
Use `println` liberally to understand what's happening:
```ruchy
ruchy> {
let x = 5;
println("x is", x);
let y = x * 2;
println("y is", y);
x + y
}
x is 5
y is 10
15
```
### 4. Type Exploration
The REPL shows you the type of expressions through their values:
```ruchy
ruchy> 42
42 # Integer
ruchy> 3.14
3.14 # Float
ruchy> "text"
"text" # String
ruchy> true
true # Boolean
ruchy> ()
() # Unit type
ruchy> [1, 2, 3]
1 # List (shows first element)
```
## 🎯 Common Patterns
### Calculator Mode
```ruchy
ruchy> let tax_rate = 0.08
0.08
ruchy> let price = 100
100
ruchy> let tax = price * tax_rate
Error: Type mismatch # Oops! Need same types
ruchy> let price = 100.0
100.0
ruchy> let tax = price * tax_rate
8.0
ruchy> let total = price + tax
108.0
ruchy> println("Total with tax:", total)
Total with tax: 108.0
()
```
### Decision Making
```ruchy
ruchy> let score = 75
75
ruchy> let grade = if score >= 90 {
"A"
} else { if score >= 80 {
"B"
} else { if score >= 70 {
"C"
} else {
"F"
}}}
"C"
ruchy> println("Your grade:", grade)
Your grade: C
()
```
### Building Up Computations
```ruchy
ruchy> let base = 100
100
ruchy> let bonus = 20
20
ruchy> let penalty = 5
5
ruchy> let final_score = base + bonus - penalty
115
ruchy> println("Final score:", final_score)
Final score: 115
()
```
## 🔍 Troubleshooting
### Common Errors and Solutions
**Type Mismatch**
```ruchy
ruchy> 3.14 * 2
Error: Type mismatch in binary operation
# Solution: Use consistent types
ruchy> 3.14 * 2.0
6.28
```
**Undefined Variable**
```ruchy
ruchy> x + 1
Error: Undefined variable: x
# Solution: Define the variable first
ruchy> let x = 10
10
ruchy> x + 1
11
```
**String + Number**
```ruchy
ruchy> "The answer is " + 42
Error: Type mismatch
# Solution: Use println for mixed types
ruchy> println("The answer is", 42)
The answer is 42
()
```
## 📖 Learning Path
1. **Start Simple**: Basic arithmetic and variables
2. **Add Logic**: Boolean expressions and if/else
3. **Use Functions**: Define and understand function syntax
4. **Pattern Match**: Learn match expressions
5. **Combine**: Build larger expressions from smaller ones
## 🚦 Quick Reference Card
```ruchy
# Numbers
42, 3.14, 2 ** 8
# Strings
"hello", "a" + "b"
# Booleans
# Variables
let x = 10
let name = "Ruchy"
# Conditionals
if condition { expr1 } else { expr2 }
# Pattern Matching
match value {
pattern1 => result1,
pattern2 => result2,
_ => default
}
# Functions
fun name(param: Type) -> RetType { body }
# Lambdas
# Printing
println("text", value1, value2)
print("no newline")
# Blocks
{
statement1;
statement2;
final_expression
}
# Commands
:help, :quit, :history, :clear, :bindings
```
## Next Steps
Once comfortable with the REPL basics:
1. Try loading example files with `:load examples/fibonacci.ruchy`
2. Experiment with self-hosting compiler development using `:bootstrap`
3. Use `:transpile` to generate minimal Rust code for self-hosting
4. Use `:compile` to see optimized generated Rust code
5. Read the [Language Specification](./SPECIFICATION.md) for advanced features
6. Check docs/execution/roadmap.yaml to see what's coming next
7. Explore examples in the [examples directory](../examples/)
Remember: The REPL is your friend and now supports self-hosting development! It's the fastest way to learn Ruchy and test compiler ideas. Keep it open while coding and use it to verify your understanding.
