# rustnim

A Rust → Nim transpiler. It parses Rust with `syn` and emits Nim source that
behaves the same way — same stdout, same exit status — when both are built and
run.

The rule the whole thing is organised around: **never approximate a semantic
you cannot represent.** If a construct doesn't map, `rustnim` says so and exits
non-zero. It never writes a file it can't stand behind.

That rule comes from a real failure. We tried an existing transpiler that
advertises Rust support on the `base16ct` crate; it emitted an empty file and
exited 0. The write-up is in [`findings/`](findings/).

## Build and run

```bash
cargo build --release
./target/release/rustnim input.rs -o out.nim
nim c out.nim
```

Several inputs are concatenated into one Nim module, in the order given — Nim
has no per-file `mod`, so items are flattened and names must not collide:

```bash
rustnim src/lib.rs src/error.rs --cfg feature=alloc -o crate.nim
```

## What works

Functions and `impl` methods, structs, enums (C-like and data-carrying),
`Option`/`Result` with `?`, `let`/`let mut`, the integer and float operators at
exact widths, `as` casts, `if`/`while`/`loop`/`for`, `match` including binding
patterns, `Vec`/slices/arrays, type aliases, function-typed parameters
(`impl Fn(A) -> B`), multi-file input, `#[cfg]`, and `println!`/`format!` with
`{}`, `{:?}`, `{:x}`, `{:b}`, positional and inline-named arguments, and
zero/space padding.

Also: the formatting trait impls (`Display`, `Debug`, `LowerHex`, `UpperHex`,
`Binary`, `Octal`) and `From`; and slice iterators — `iter`, `iter_mut`,
`enumerate`, `zip`, `chunks_exact`, `chunks_exact_mut`, `windows` — resolved
into a single index loop where each binding is an lvalue into the original
container, so `*d = v` through `iter_mut()` reaches the caller's slice.
Borrowed slices are views, not copies, including as return types.

Rejected with a reason, rather than guessed at: `i128`/`u128`, generics,
closures, `unsafe`, trait impls other than the ones above, iterator adaptors
with no index-loop equivalent (`map`, `filter`, `take_while`), float→int casts,
and any standard-library method that isn't mapped.

## base16ct

`tests/cases/026-base16ct-crate/` transpiles base16ct 1.0.0's `error.rs` and
`mixed.rs` byte-for-byte as published on crates.io, plus `lib.rs`'s
`decoded_len`, `encoded_len` and `decode_inner` verbatim. Its decoder output is
byte-identical to rustc's — lower, upper and mixed hex, both error variants,
and the `Display` strings. That is the crate the transpiler in
[`findings/`](findings/) emitted an empty file for.

The rest of the crate needs closures, `unsafe`, and struct fields of view type;
[`DESIGN.md`](DESIGN.md) says which file needs which.

## Tests

```bash
cargo test
```

The tests are differential, with rustc as the oracle. Each case in
`tests/cases/` is compiled by rustc and run, transpiled and compiled by Nim and
run, and the two stdouts and exit statuses must match. Building anything less
than that — checking the Nim output "looks right", say — is how you end up
shipping the bug in `findings/`. `rustnim` exiting 0 with a missing or empty
output file is a hard failure, and so is an empty corpus.

rustc is invoked without `-O` so debug-profile overflow checks are on, which is
the matching pair for `nim c`'s defaults.

Nim is found at `.nim-toolchain/bin/nim` in the repo root or any parent, or via
`RUSTNIM_NIM`. Run a single case with:

```bash
RUSTNIM_CASE=005 cargo test --test differential -- --nocapture
```

## Layout

| file | role |
|---|---|
| `src/ty.rs` | Rust type → Nim type, exact widths, explicit rejections |
| `src/lower.rs` | items, statements, expressions → Nim |
| `src/fmt.rs` | `println!`/`format!` format strings |
| `src/prelude.nim` | `Option`/`Result`, panic, `Display`/`Debug` runtime |
| `tests/differential.rs` | the runner above |

[`DESIGN.md`](DESIGN.md) has the reasoning: how each construct is mapped, what
was settled by running both compilers rather than by reading docs, and what's
still open.