Align RPython syntax, docs, and end-to-end tests

- Make user-facing type strings match the language syntax (Int/Unit, Maybe[T], Result[Ok, Err])
- Improve ADT type parsing (allow multi-field constructors like )
- Remove stale #[ignore] tests and strengthen parser tests (avoid “is_ok()” false positives)
- Add/expand Beecrowd end-to-end harness + fixtures for syntax/runtime coverage
- Refresh docs: README + refactor log, and rewrite stdlib docs as STDLIB.md
- Repo hygiene: ignore /llm and keep outputs consistent (lists/tuples/monads print as literals)

Author: RafaelLopes23

.gitignore

@@ -1,2 +1,4 @@
 /target
-.idea
+.idea/
+.ideallm/
+/llm/

README.md

@@ -163,11 +163,14 @@ asserttrue(result == 120, "5! should be 120");
 Anonymous functions can be assigned to variables or passed as arguments.
 
 ```text
-val add = lambda (a: Int, b: Int) -> Int: return a + b end;
-val sum = add(2, 3);
+def apply(f: fn(Int, Int) -> Int, a: Int, b: Int) -> Int:
+    return f(a, b);
+end;
+
+val sum = apply(lambda (a: Int, b: Int) -> Int: return a + b end, 2, 3);
 ```
 
-> **Current limitation:** Lambdas are parsed correctly but not yet fully implemented in the interpreter.
+> **Current limitation:** Lambdas are supported as first-class function values (especially when passed as arguments to functions expecting a `fn(...) -> ...` type), but calling a lambda *via a variable name* is not fully supported yet in all contexts. Prefer `def` for named functions, or pass lambdas directly as arguments.
 
 ---
 
@@ -177,13 +180,16 @@ Metabuiltins are functions implemented in Rust and exposed to user code. They ha
 
 ### I/O
 
-| Function                  | Description                                      |
-|---------------------------|--------------------------------------------------|
-| `input(prompt?)`          | Read a line from stdin; optional prompt string.  |
-| `input_int(prompt?)`      | Read and parse an integer from stdin.            |
-| `input_real(prompt?)`     | Read and parse a real number from stdin.         |
-| `print(value)`            | Print `value` without trailing newline.          |
-| `print_line(value)`       | Print `value` followed by a newline.             |
+| Function                  | Description                                                    |
+|---------------------------|----------------------------------------------------------------|
+| `input()`                 | Read a line from stdin. Returns a `String`.                    |
+| `input(prompt)`           | Print `prompt`, then read a line from stdin.                   |
+| `input_int()`             | Read and parse an integer from stdin.                          |
+| `input_int(prompt)`       | Print `prompt`, then read and parse an integer.                |
+| `input_real()`            | Read and parse a real number from stdin.                       |
+| `input_real(prompt)`      | Print `prompt`, then read and parse a real number.             |
+| `print(value)`            | Print `value` without trailing newline.                        |
+| `print_line(value)`       | Print `value` followed by a newline.                           |
 
 ### Conversion
 
@@ -202,11 +208,19 @@ Metabuiltins are functions implemented in Rust and exposed to user code. They ha
 | `join(values: List[String], sep)` | Join a list of strings with a separator.                   |
 | `len(value)`                      | Return the length of a string, list, or tuple.             |
 
+### Tuples
+
+| Function                  | Description |
+|--------------------------|-------------|
+| `tuple_get(value, index)` | Return the element at `index` from a tuple (or an error string on invalid input). |
+
 ### Files
 
 | Function                      | Description                                                       |
 |-------------------------------|-------------------------------------------------------------------|
-| `open(path, mode, content)` | Open a file. Modes: `r` (read), `w` (write), `a` (append).        |
+| `open(path, "r")`             | Read and return the contents of `path`.                           |
+| `open(path, "w", content)`    | Write `content` to `path`, overwriting existing content.          |
+| `open(path, "a", content)`    | Append `content` to `path`.                                       |
 
 ---
 
@@ -226,7 +240,7 @@ RPython provides two monadic types for representing optional or fallible values:
 - `unwrap(value)` — extracts the inner value (panics if `Nothing` or `Err`)
 - `tryUnwrap(value)` — extracts or propagates errors automatically
 
-> **Current limitation:** The parser does not yet support `Just()`, `Nothing`, `Ok()`, and `Err()` as expression syntax. These types exist in the AST and type system, and are used internally by the interpreter and type checker. Parser support for constructing these values from source code is planned for a future release.
+> Note: `Just(value)`, `Nothing`, `Ok(value)`, and `Err(error)` are supported as expression syntax.
 
 ---
 
@@ -293,7 +307,7 @@ src/
 - **`type_checker/`** — Validates types; checks function signatures and return types.
 - **`interpreter/statement_execute.rs`** — Executes statements; handles loops with `break`/`continue`.
 - **`interpreter/expression_eval.rs`** — Evaluates expressions; dispatches metabuiltin calls.
-- **`stdlib/standard_library.rs`** — Implements 13 metabuiltins.
+- **`stdlib/standard_library.rs`** — Implements the metabuiltins table and its built-in functions.
 - **`pretty_print/`** — AST-to-source formatter (see below).
 
 ### Pretty Printer
@@ -376,7 +390,7 @@ The interpreter reads from stdin and writes to stdout, making it suitable for au
 4. **No interactive REPL:** only file-based execution is supported.
 5. **Limited error messages:** parser and type checker errors are functional but not always user-friendly.
 6. **No tail-call optimization:** deep recursion may overflow the stack.
-7. **Maybe/Result constructors:** `Just()`, `Nothing`, `Ok()`, `Err()` cannot be parsed from source code yet.
+7. **Maybe/Result constructors:** supported as expression syntax, but values cannot be destructured without pattern matching.
 8. **Small standard library:** only a small set of metabuiltins is available (basic I/O, conversions, simple string/list helpers); there are no rich libraries for math, dates/times, networking, etc.
 9. **No exceptions:** there is no `try`/`catch` mechanism or exception hierarchy; errors are represented via `Maybe`/`Result` types or abort execution with an error message.
 10. **No objects or methods:** there are no classes, interfaces, or method calls; programs are written with functions, lists/tuples, and algebraic data types.

docs/AI_ASSISTED_REFACTORING_SESSION_MAR_22_2026.md

@@ -0,0 +1,127 @@
+# AI-Assisted Refactoring Session (March 22, 2026)
+
+## Objective
+To align the existing R-Python language implementation (`parser`, `ast`, and `pretty_print`) precisely with the features documented in the project's `README.md`.
+
+## Issues Identified
+During an extensive codebase scan comparing the `README.md` syntax definitions against what the R-Python Rust frontend actually implemented, several inconsistencies were detected:
+
+1. **Composite Types Parsing Discrepancies**:
+   - Lists were documented as `List[T]` but parsed natively as `[T]`.
+   - Tuples were documented as `Tuple[T1, T2]` but parsed via parentheses as `(T1, T2)`.
+   - Functions were documented as `fn(T1, T2) -> R` but parsed without the `fn` keyword as `(T1, T2) -> R`.
+
+2. **Error Handling Implementation Gaps**:
+   - The README listed features like `unwrap(value)`, `tryUnwrap(value)`, `isNothing(maybe)`, and `isError(result)` as working available functions.
+   - However, they hadn't been fully mapped structurally into the primary expression parsing phase (`src/parser/parser_expr.rs`) which blocked their `.rpy` usage.
+
+## Fixes Implemented
+
+### 1. Abstract Syntax Tree & Parser Adjustments
+Modules adjusted: `src/parser/parser_type.rs` and `src/ir/ast.rs`
+- Adapted `parse_list_type` to use the `List` keyword wrapper for generating `Type::TList`.
+- Adapted `parse_tuple_type` to use the `Tuple` keyword wrapper for generating `Type::TTuple`.
+- Adapted `parse_function_type` to expect the `fn` keyword before parameter listings.
+- Formatter traits (`fmt::Display`) on AST nodes were updated to match the strict `List[...]` and `Tuple[...]` syntax, keeping compiler errors aligned with user-facing expectations.
+
+### 2. Error Handling Integrated
+Modules adjusted: `src/parser/parser_expr.rs`
+- Exposed dedicated recursive parsers directly translating to native AST functional nodes:
+  - `unwrap(expr)` routes to `Expression::Unwrap`
+  - `tryUnwrap(expr)` routes to `Expression::Propagate`
+  - `isNothing(expr)` routes to `Expression::IsNothing`
+  - `isError(expr)` routes to `Expression::IsError`
+- Allowed true integration natively in `.rpy` files with zero runtime modifications required underneath (as interpreter and type checking logic natively recognized these AST branches already).
+
+### 3. Pretty Printer Formatter Corrections
+Modules adjusted: `src/pretty_print/pretty_type.rs`
+- Reverted the `ToDoc` implementations over types to utilize `List[T]`, `Tuple[T1, T2]` and `fn(...) -> R`.
+- Handled indentation properly for multiline implementations passing the Rust test suite.
+
+### 4. Beecrowd Edge Case Fixed
+- Re-tested library compilation checking legacy RPython Beecrowd tasks: discovered and fixed an invalid fixture mismatch in the tests context (`1035 - Selection Test`) which broke testing bounds. Re-aligned the IO mappings passing the entire testing suite successfully.
+
+## Outcome
+The standard library definitions matching `README.md` constraints now genuinely behave 1:1 against file inputs while keeping functional paradigms intact. Execution and tests pass on `0.1.0`.
+
+---
+
+## Follow-up Refactors (March 22, 2026)
+
+After the initial README-alignment work above, we performed additional refactors focused on *end-to-end feature testing* (parser → type checker → interpreter → Beecrowd fixtures) without relying on “dead code” branches.
+
+### 5. Maybe/Result Constructors Supported as Expressions
+Modules adjusted: `src/parser/parser_expr.rs` and `README.md`
+- Added expression parsing for the constructors:
+   - `Just(value)` → `Expression::CJust(...)`
+   - `Nothing` → `Expression::CNothing`
+   - `Ok(value)` → `Expression::COk(...)`
+   - `Err(error)` → `Expression::CErr(...)`
+- Added parser unit tests covering these constructors.
+- Updated `README.md` to remove the outdated limitation that constructors could not be written in source code.
+
+Why this mattered: the `unwrap/isNothing/isError/tryUnwrap` family becomes meaningfully testable only when source programs can actually construct `Maybe`/`Result` values.
+
+### 6. Tuple Accessor Builtin (`tuple_get`)
+Modules adjusted: `src/stdlib/standard_library.rs` and `src/interpreter/expression_eval.rs`
+- Added a new metabuiltin: `tuple_get(value, index)`.
+- Wired it into the interpreter builtin dispatch.
+- Updated stdlib table tests to include the new builtin.
+
+Why this mattered: without tuple element access, `Tuple[...]` can be parsed and type-checked, but is hard to use in *real* algorithmic problems (including Beecrowd), because values are otherwise opaque.
+
+### 7. Beecrowd “No Workarounds” Coverage (Problem 1172)
+Modules/files adjusted: `tests/fixtures/beecrowd/1172/solution.rpy`
+- Rewrote the solution so that the newly-implemented features are exercised in the *actual* executed code path (no `if False:` blocks):
+   - typed parameters using `List[Int]` and `Tuple[Int, Int]`
+   - higher-order function usage via `fn(Tuple[Int, Int]) -> Int`
+   - real runtime use of `Ok(...)` / `Err(...)` with `isError(...)` and `unwrap(...)`
+   - tuple element retrieval via `tuple_get(...)`
+- Kept the same folder/fixture structure and did not change any existing Beecrowd problems already in the suite.
+
+### 8. Example Script Updated (`hello_io.rpy`)
+File adjusted: `examples/hello_io.rpy`
+- Updated the demo to show the new constructors and error-handling operations without intentionally triggering a runtime panic.
+
+## Updated Outcome
+The codebase now supports the README composite type syntax *and* can exercise `Maybe`/`Result` values end-to-end from source code, including in Beecrowd-style fixture tests, while keeping the existing tests intact.
+
+### 9. Runtime Output Formatting (Lists/Tuples/Monads)
+Modules adjusted: `src/stdlib/standard_library.rs`
+- Fixed `print(...)`, `print_line(...)`, and `to_string(...)` output for composite runtime values.
+- Previously, tuples and lists printed using Rust `Debug` formatting (e.g., `Tuple([CInt(404), CString("Not Found")])`), leaking internal AST wrapper names.
+- Updated the stdlib’s internal value-to-string conversion so runtime values render using RPython literal-like formatting:
+   - lists as `[1, 2, 3]`
+   - tuples as `(404, "Not Found")`
+   - monads as `Ok(999)`, `Err("boom")`, `Just(1)`, `Nothing`
+
+Why this mattered: examples (like `hello_io.rpy`) and Beecrowd-style outputs should reflect *language-level* values, not internal interpreter representation.
+
+### 10. Documentation Re-validation (README + STDLIB)
+Files adjusted: `README.md`, `src/stdlib/STDLIB.md`
+- Re-validated `README.md` against the current implementation.
+   - Updated the lambda example to a pattern that is known to work reliably: passing `lambda (...) -> ...` as a first-class function argument.
+   - Documented the `tuple_get(value, index)` builtin in the “Standard Library” section.
+   - Removed the stale hard-coded “13 metabuiltins” count (the exact number changes as the stdlib evolves).
+- Renamed and rewrote the standard library documentation as `src/stdlib/STDLIB.md` and translated it to English.
+
+Why this mattered: in this project, the root README acts as the user-facing language spec; keeping it and the stdlib docs synchronized avoids regressions where supported syntax exists but is undocumented (or vice-versa).
+
+### 11. Type Display Formatting Alignment (User-Facing Errors)
+Module adjusted: `src/ir/ast.rs`
+- Updated `fmt::Display` for `Type` to reflect the README/parser syntax for type names:
+   - `Int`, `Real`, `Boolean`, `String`, `Unit`, `Any`
+   - `Maybe[T]` and `Result[Ok, Err]` (instead of angle-bracket formatting)
+
+Why this mattered: type checker error messages should use the same type spellings that users write in `.rpy` programs.
+
+### 12. Test Suite Hygiene (Remove `#[ignore]` + Make Assertions Meaningful)
+Files adjusted: `src/parser/parser_expr.rs`, `tests/parser_tests.rs`, `src/parser/parser_type.rs`
+- Removed `#[ignore]` from parser unit/integration tests where the underlying features are already implemented.
+- Updated stale expectations to match current AST semantics:
+   - `if` parsing expectations were updated to `Statement::IfChain` (the current representation).
+   - Adjusted the ADT-related test cases to reflect the current limitation that ADT declarations are parsed as *types* (via `parse_type`) and not as top-level statements.
+- Strengthened “invalid expression” tests to account for prefix-friendly parsing (a partial parse that leaves unconsumed input is treated as invalid for full-program parsing).
+- Extended ADT constructor type parsing to allow multiple basic field types (e.g., `| Rectangle Int Int`).
+
+Why this mattered: ignored tests tend to rot and hide regressions. By making them run and ensuring they assert the right invariants, the suite becomes a better executable spec for the README.

examples/hello_io.rpy

@@ -163,4 +163,45 @@ val contents2 = open(test_file, "r");
 var _ = print("After append: ");
 var _ = print_line(contents2);
 
+var _ = print_line("=== 16. Explicit Typing & Error Handling ===");
+def print_typed_list(lst: List[Int]) -> Int:
+    var _ = print("Typed List[Int]: ");
+    var _ = print_line(lst);
+    return 0;
+end;
+
+def print_typed_tuple(tup: Tuple[Int, String]) -> Int:
+    var _ = print("Typed Tuple[Int, String]: ");
+    var _ = print_line(tup);
+    return 0;
+end;
+
+def higher_order(func: fn(Int) -> Int, value: Int) -> Int:
+    return func(value);
+end;
+
+def duplicate(x: Int) -> Int:
+    return x * 2;
+end;
+
+var _ = print_typed_list([100, 200, 300]);
+var _ = print_typed_tuple((404, "Not Found"));
+
+var _ = print("higher_order(duplicate, 21): ");
+var _ = print_line(higher_order(duplicate, 21));
+
+val maybe_val = Nothing;
+var _ = print("isNothing(Nothing)? ");
+var _ = print_line(isNothing(maybe_val));
+
+val ok_val = Ok(999);
+var _ = print("isError(Ok(999))? ");
+var _ = print_line(isError(ok_val));
+var _ = print("unwrap(Ok(999)): ");
+var _ = print_line(unwrap(ok_val));
+
+val err_val = Err("boom");
+var _ = print("isError(Err(boom))? ");
+var _ = print_line(isError(err_val));
+
 var _ = print_line("=== Demo Complete ===");

examples/input_demo.rpy

@@ -0,0 +1,35 @@
+var _ = print_line("=== RPython Input Demo ===");
+var _ = print_line("This demo showcases input(), input_int(), and input_real()");
+var _ = print_line("");
+
+var _ = print_line("--- input() ---");
+val name = input("Enter your name: ");
+var _ = print("Hello, ");
+var _ = print(name);
+var _ = print_line("!");
+
+var _ = print_line("");
+var _ = print_line("--- input_int() ---");
+val age = input_int("Enter your age: ");
+var _ = print("In 10 years you will be ");
+var _ = print_line(age + 10);
+
+var _ = print_line("");
+var _ = print_line("--- input_real() ---");
+val price = input_real("Enter a price: ");
+val tax = price * 0.1;
+var _ = print("Price with 10% tax: ");
+var _ = print_line(to_string_fixed(price + tax, 2));
+
+var _ = print_line("");
+var _ = print_line("--- Combining inputs ---");
+val a = input_int("Enter first number: ");
+val b = input_int("Enter second number: ");
+var _ = print(a);
+var _ = print(" + ");
+var _ = print(b);
+var _ = print(" = ");
+var _ = print_line(a + b);
+
+var _ = print_line("");
+var _ = print_line("=== Demo Complete ===");

src/interpreter/expression_eval.rs

@@ -560,6 +560,40 @@ pub fn eval_function_call(
                 let mut meta_env: Environment<Expression> = Environment::new();
 
                 match func_name.as_str() {
+                    // tuple_get(value, index) -> any (element) or error string
+                    "tuple_get" => {
+                        if args.len() != 2 {
+                            return Err(
+                                "[Runtime Error] tuple_get expects exactly 2 arguments".into(),
+                            );
+                        }
+
+                        let value = match eval(args[0].clone(), env)? {
+                            ExpressionResult::Value(v) => v,
+                            ExpressionResult::Propagate(e) => {
+                                return Ok(ExpressionResult::Propagate(e))
+                            }
+                        };
+                        let index = match eval(args[1].clone(), env)? {
+                            ExpressionResult::Value(v) => v,
+                            ExpressionResult::Propagate(e) => {
+                                return Ok(ExpressionResult::Propagate(e))
+                            }
+                        };
+
+                        meta_env.map_variable("value".to_string(), false, value);
+                        meta_env.map_variable("index".to_string(), false, index);
+
+                        let stmt = meta_fn(&mut meta_env);
+                        if let Statement::Return(expr) = stmt {
+                            Ok(ExpressionResult::Value(*expr))
+                        } else {
+                            Err(
+                                "[Runtime Error] tuple_get builtin did not return a value".into(),
+                            )
+                        }
+                    }
+
                     // input([prompt]) -> String
                     "input" => {
                         if let Some(prompt_expr) = args.get(0) {