RPython is a statically typed, interpreted language with Python-inspired syntax. Unlike Python, it uses explicit end delimiters instead of indentation and requires type annotations on function signatures. The entire toolchain—lexer, parser, type checker, interpreter, and standard library—is implemented in Rust.

Tip: View README.md in Raw mode on GitHub to copy code snippets without HTML rendering.

1. Motivation
2. Language Overview
3. Type System
4. Control Flow
5. Functions
6. Standard Library (Metabuiltins)
7. Error Handling
8. Algebraic Data Types
9. Test Blocks
10. Project Architecture
11. Build & Test
12. Running Programs
13. Current Limitations
14. Contributing

RPython was created as a teaching tool for undergraduate courses on programming language implementation. The codebase demonstrates:

• Parsing with combinators: the parser uses nom to build an AST from source text.
• Scoped environments: lexical scoping is implemented via a stack of symbol tables.
• Static type checking: a type checker validates function signatures and expressions before execution.
• Tree-walking interpretation: the interpreter directly evaluates the AST.

The language surface resembles Python to lower the barrier for students, while the explicit block delimiters and mandatory type annotations expose concepts often hidden in dynamic languages.

val pi = 3.14159;
var counter = 0;
counter = counter + 1;

• val declares an immutable variable; reassignment is a compile-time error.
• var declares a mutable variable.

Note: RPython does not support comments in source code. The examples in this README omit comments for accuracy.

Note: Equality operators support numbers, strings, and booleans. Ordering operators are currently limited to numbers.

RPython uses explicit, static types for function parameters and return values. Variables infer their type from the initializer expression.

• Int — 32-bit signed integer
• Real — 64-bit floating point
• Boolean — True or False
• String — UTF-8 text
• Unit — returned by side-effect-only functions (equivalent to void)
• Any — escape hatch; matches any type (used sparingly)

• List[T] — homogeneous list of elements of type T
• Tuple[T1, T2, ...] — fixed-size, heterogeneous tuple
• Maybe[T] — optional value (Just(value) or Nothing)
• Result[Ok, Err] — success/failure carrier (Ok(value) or Err(error))
• fn(T1, T2) -> R — first-class function type

if score >= 90:
    grade = "A";
elif score >= 80:
    grade = "B";
else:
    grade = "C";
end

A single end closes the entire if-chain. The elif and else keywords introduce new branches without requiring separate end markers.

var i = 0;
while i < 5:
    var _ = print_line(to_string(i));
    i = i + 1;
end;

for x in [1, 2, 3]:
    var _ = print_line(to_string(x));
end;

• break exits the innermost loop immediately.
• continue skips to the next iteration.

Functions require type annotations for parameters and return type.

def factorial(n: Int) -> Int:
    if n <= 1:
        return 1;
    else:
        return n * factorial(n - 1);
    end;
end;

val result = factorial(5);
asserttrue(result == 120, "5! should be 120");

Syntax note: Block statements (if, while, for, def) require a semicolon after the closing end when followed by additional statements at the same level.

Anonymous functions can be assigned to variables or passed as arguments.

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 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.

Metabuiltins are functions implemented in Rust and exposed to user code. They handle I/O, type conversions, and common operations.

RPython provides two monadic types for representing optional or fallible values: Maybe[T] and Result[Ok, Err].

• Maybe[T] — Optional value: Just(value) or Nothing
• Result[Ok, Err] — Success/failure: Ok(value) or Err(error)

• isNothing(maybe) — returns True if the value is Nothing
• isError(result) — returns True if the value is Err
• unwrap(value) — extracts the inner value (panics if Nothing or Err)
• tryUnwrap(value) — extracts or propagates errors automatically

Note: Just(value), Nothing, Ok(value), and Err(error) are supported as expression syntax.

ADTs can be declared with multiple constructors. Pattern matching is not yet implemented; values are constructed and passed around opaquely.

Current limitation: ADT declarations are parsed as types but cannot yet be declared as top-level statements. The syntax shown below is the planned syntax; it is not yet functional.

data Shape:
    | Circle Int
    | Rectangle Int Int
end

val c = Circle(5);
val r = Rectangle(3, 4);

Inline test definitions allow embedding unit tests directly in source files.

test addition_works():
    val result = 2 + 2;
    asserttrue(result == 4, "2 + 2 should be 4");
end

Assertions:

src/
├── ir/              # AST definitions (expressions, statements, types)
├── parser/          # nom-based parsers for expressions, statements, types
├── type_checker/    # Static type checking for expressions and statements
├── interpreter/     # Tree-walking interpreter and test runner
├── stdlib/          # Metabuiltins table and implementations
├── pretty_print/    # AST → readable source formatter
├── environment/     # Scoped symbol tables (variables, functions, types)
└── main.rs          # Entry point (currently test-driven)

• ir/ast.rs — Defines Expression, Statement, Type, Function, and ADT structures.
• parser/parser_stmt.rs — Parses statements (if, while, for, def, break, continue, etc.).
• parser/parser_expr.rs — Parses expressions (literals, operators, function calls).
• 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 the metabuiltins table and its built-in functions.
• pretty_print/ — AST-to-source formatter (see below).

The pretty_print module converts parsed AST nodes back into readable RPython source code. It is primarily used for:

• Testing round-trip correctness: parse → pretty-print → compare.
• Debugging: inspect how the parser understood your code.
• Future tooling: code formatters, IDE integrations.

The pretty printer is not invoked during normal program execution. It is available via the prelude module for programmatic use:

use r_python::prelude::{pretty, ToDoc};
// pretty(80, &statement.to_doc()) → formatted String

Optional feature flags enable performance instrumentation:

# Timing metrics
cargo run --features pp-timing --example pp_timing

# Profile counters
cargo run --features pp-profile --example pp_bench

• Rust (stable toolchain)
• Cargo (bundled with Rust)

# Clone the repository
git clone https://github.com/UnBCIC-TP2/r-python.git
cd r-python

# Build the project
cargo build

# Run all tests
cargo test

# Run tests with output (useful for debugging)
cargo test -- --nocapture

The test suite currently includes 270+ unit tests covering the parser, type checker, interpreter, and standard library.

RPython includes a CLI to execute .rpy files directly:

# Run a program
cargo run -- path/to/program.rpy

# Or build first, then run the binary
cargo build --release
./target/release/r-python path/to/program.rpy

The interpreter reads from stdin and writes to stdout, making it suitable for automated judging systems like beecrowd.

1. No module system: all code lives in a single file.
2. No pattern matching: ADT constructors can be built but not destructured.
3. No comments: the parser does not support # or any comment syntax.
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: 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.
11. No concurrency or async: the language has no built-in support for threads, async/await, or parallel execution.
12. Interpreter-only, unoptimized: execution is performed by a tree-walking interpreter without bytecode/JIT or optimization passes, so performance is below production-grade VMs/compilers.
13. Minimal tooling: beyond the CLI and internal pretty printer, there is no dedicated debugger, formatter binary, or IDE integration yet.

Contributions are welcome! Please read the contribution guides before submitting issues or pull requests:

• Contributing Guidelines (English)
• Guia de Contribuição (Português)