docs: prepare some samples of lox language and also write the readme file

Author: aymaneelmaini

README.md

@@ -0,0 +1,98 @@
+# Lox Interpreter
+
+A complete implementation of the Lox programming language interpreter in Kotlin, following the principles from "Crafting Interpreters".
+
+## Features
+
+- **Lexical Analysis**: Full tokenization with keyword and identifier distinction
+- **Parsing**: Recursive descent parser building an abstract syntax tree
+- **Variables**: Dynamic typing with `var` declarations and lexical scoping
+- **Functions**: First-class functions with named (`fun`) and anonymous (`fn`) syntax, closures, and proper tail behavior
+- **Classes**: Object-oriented programming with inheritance, instance fields, and methods
+- **Static Methods**: Class-level methods accessible directly on the class
+- **Native Functions**: Built-in functions for I/O and timing (clock, println, scan, input)
+- **Control Flow**: if/else statements and while loops
+- **Operators**: All standard arithmetic, comparison, logical, and assignment operators
+- **Scope Resolution**: Static analysis pass that pre-computes variable binding distances for efficient runtime lookup
+- **Error Handling**: Proper runtime error reporting with token information
+
+## Language Syntax Basics
+
+Variables and assignment:
+```
+var x = 10;
+x = 20;
+```
+
+Functions:
+```
+fun greet(name) {
+  println("Hello, " + name);
+}
+
+greet("Alice");
+```
+
+Anonymous functions:
+```
+var add = fn(a, b) { a + b };
+println(add(3, 4));
+```
+
+Classes and inheritance:
+```
+class Animal {
+  init(name) {
+    this.name = name;
+  }
+  
+  speak() {
+    println(this.name + " makes a sound");
+  }
+}
+
+class Dog > Animal {
+  speak() {
+    println(this.name + " barks");
+  }
+}
+
+var dog = Dog("Buddy");
+dog.speak();
+```
+
+## Building and Running
+
+Compile the Kotlin code and run the interpreter:
+
+```bash
+kotlinc -include-runtime -d lox.jar src/*.kt
+java -jar lox.jar script.lox
+```
+
+Or use the REPL for interactive mode.
+
+## Implementation Highlights
+
+- **Visitor Pattern**: AST traversal for both parsing and interpretation
+- **Environment Chains**: Linked scopes for variable storage and lookup
+- **Resolver**: Two-pass compilation approach (resolve then execute) for scope analysis
+- **LoxCallable**: Interface for both user-defined and native functions
+- **Exception-based Control Flow**: RuntimeReturn for return statements, RuntimeError for errors
+
+## Project Structure
+
+- `Interpreter.kt`: Core execution engine with expression and statement visitors
+- `Expr.kt`: AST node definitions for expressions
+- `Stmt.kt`: AST node definitions for statements
+- `Scanner.kt`: Lexical analysis
+- `Parser.kt`: Syntax analysis and AST building
+- `Resolver.kt`: Static scope analysis
+- `Environment.kt`: Scope and variable storage
+- `LoxCallable.kt`: Interface for callable objects
+- `LoxClass.kt`, `LoxInstance.kt`: Object-oriented features
+- `Token.kt`: Token representation
+
+## References
+
+This implementation closely follows the Lox language design and interpreter architecture from "Crafting Interpreters" by Robert Nystrom, adapted to Kotlin's modern language features.

samples/anonymous_functions.lox

@@ -0,0 +1,10 @@
+var numbers = 5;
+var double = fn(n) { n * 2 };
+
+println(double(numbers));
+
+var apply = fn(func, value) {
+  func(value)
+};
+
+println(apply(double, 10));

samples/classes.lox

@@ -0,0 +1,19 @@
+class Person {
+  init(name, age) {
+    this.name = name;
+    this.age = age;
+  }
+  
+  introduce() {
+    println("Hi, I'm " + this.name + " and I'm " + this.age + " years old");
+  }
+  
+  birthday() {
+    this.age = this.age + 1;
+    println(this.name + " is now " + this.age);
+  }
+}
+
+var alice = Person("Alice", 30);
+alice.introduce();
+alice.birthday();

samples/control_flow.lox

@@ -0,0 +1,12 @@
+var x = 10;
+var y = 20;
+
+if (x < y) {
+  println("x is less than y");
+}
+
+var counter = 0;
+while (counter < 5) {
+  println("Counter: " + counter);
+  counter = counter + 1;
+}

samples/example_fibonacci.lox

@@ -0,0 +1,14 @@
+fun fibonacci(n) {
+  if (n <= 1) {
+    n
+  } else {
+    fibonacci(n - 1) + fibonacci(n - 2)
+  }
+}
+
+var start = clock();
+var result = fibonacci(30);
+var elapsed = clock() - start;
+
+println("fibonacci(30) = " + result);
+println("Computed in " + elapsed + " seconds");

samples/example_quiz.lox

@@ -0,0 +1,33 @@
+class Quiz {
+  static run() {
+    var score = 0;
+    
+    var answer1 = input("What is 2 + 2? ");
+    if (answer1 == "4") {
+      println("Correct!");
+      score = score + 1;
+    } else {
+      println("Wrong! The answer is 4");
+    }
+    
+    var answer2 = input("What is the capital of France? ");
+    if (answer2 == "Paris") {
+      println("Correct!");
+      score = score + 1;
+    } else {
+      println("Wrong! The answer is Paris");
+    }
+    
+    var answer3 = input("Is the Earth flat? ");
+    if (answer3 == "no") {
+      println("Correct!");
+      score = score + 1;
+    } else {
+      println("Wrong! The answer is no");
+    }
+    
+    println("Your score: " + score + "/3");
+  }
+}
+
+Quiz.run();

samples/example_user_db.lox

@@ -0,0 +1,22 @@
+class User {
+  init(name, email) {
+    this.name = name;
+    this.email = email;
+  }
+  
+  static create() {
+    var name = input("Enter name: ");
+    var email = input("Enter email: ");
+    User(name, email)
+  }
+  
+  display() {
+    println("User: " + this.name + " (" + this.email + ")");
+  }
+}
+
+var user1 = User.create();
+user1.display();
+
+var user2 = User.create();
+user2.display();

samples/functions.lox

@@ -0,0 +1,18 @@
+fun add(a, b) {
+  a + b
+}
+
+println(add(5, 3));
+
+fun makeCounter() {
+  var count = 0;
+  return fn(step) {
+    count = count + step;
+    count
+  };
+}
+
+var counter = makeCounter();
+println(counter(1));
+println(counter(1));
+println(counter(5));

samples/inheritance.lox

@@ -0,0 +1,27 @@
+class Animal {
+  init(name) {
+    this.name = name;
+  }
+  
+  speak() {
+    println(this.name + " makes a sound");
+  }
+}
+
+class Dog > Animal {
+  speak() {
+    println(this.name + " barks");
+  }
+}
+
+class Cat > Animal {
+  speak() {
+    println(this.name + " meows");
+  }
+}
+
+var dog = Dog("Rex");
+var cat = Cat("Whiskers");
+
+dog.speak();
+cat.speak();

samples/native_input.lox

@@ -0,0 +1,7 @@
+var age = input("How old are you? ");
+println("You are " + age + " years old");
+
+var answer = input("Enter yes or no: ");
+if (answer == "yes") {
+  println("You said yes!");
+}