# Transplang

Translate a strict subset of Python scripts into compilable Rust programs.

---

## Example

**`script.py`**

```python
def total(nums):
    s = 0
    for n in nums:
        s += n
    return s

print(total([1, 2, 3, 4]))
```

**Generated `out.rs`**

```rust
fn total(nums: Vec<i32>) -> i32 {
    let mut s: i32 = 0;
    for n in nums {
        s = s + n;
    }
    s
}

fn main() {
    println!("{}", total(vec![1, 2, 3, 4]));
}
```

---

## Supported Python constructs

| Construct | Notes |
|---|---|
| `def` functions | scalar and Vec parameters |
| Integer literals | mapped to `i32` |
| String literals | mapped to `&str` |
| List literals | mapped to `vec![…]` |
| Variable assignment | `let` / `let mut` |
| Augmented assignment | `+=`, `-=`, `*=`, `/=` |
| Arithmetic | `+`, `-`, `*`, `/` |
| `for x in y` loops | iterating over lists or Vec params |
| `return` | last return rendered as tail expression |
| `print()` | mapped to `println!` |

---

## Unsupported (rejected with a clear error)

- `import` statements
- `class` definitions
- `if` / `while` / `with` / `try`
- `async` / `await`
- Decorators
- Comprehensions
- Dicts, sets
- Attribute access (`obj.attr`)
- Subscript access (`x[i]`)

---

## Architecture

```
Python file
    ↓
ast.parse()          [parser.py]
    ↓
SemanticModel        [analyzer.py]
    ↓
RustIR               [mapper.py]
    ↓
Rust source          [rust_generator.py]
```

No runtime dependencies; stdlib only (`ast`, `argparse`, `pathlib`).

## Install

```bash
pip install transplang
```

Or from source:

```bash
git clone https://github.com/calchiwo/transplang.git
cd transplang
pip install -e .
```

---

## Usage

```bash
transplang translate script.py --to rust
```

Write output to a file:

```bash
transplang translate script.py --to rust --output out.rs
rustc out.rs && ./out
```

---

## Running tests

```bash
pip install pytest
pytest
```

Or without pytest:

```bash
python -m unittest discover -s tests
```

---

## Scope

Transplang currently focuses on a very small subset of Python and Rust.

The goal of this version is simple: demonstrate that structured translation between programming languages can work in practice when the surface area is tightly controlled.

Only a limited set of constructs are supported:

* functions
* integers
* lists
* loops
* basic arithmetic
* `print`

Anything outside this scope is intentionally rejected.

This constraint keeps the system deterministic and makes it easier to reason about translation correctness.

## Why I started small

Real software systems are complex. Languages differ in runtime models, type systems, and ecosystem conventions.

Attempting to translate entire applications immediately would produce unreliable results.

Instead, Transplang begins with a narrow slice of functionality to test the core idea: that a program can be analyzed structurally and rebuilt in another language.

If this approach proves reliable on small programs, the surface area can expand over time.

## Long-term direction

Programs written in different languages ultimately describe the same underlying elements:

* state
* transformations
* control flow
* side effects

Transplang explores whether those elements can be extracted and reconstructed in another language environment.

The current prototype should be viewed as a minimal experiment around that idea.


## Author

[Caleb Wodi](https://github.com/calchiwo)