rustnim — a Rust → Nim transpiler
Status
Milestone 1's decoder goal is reached. 31 differential cases, 27
behavioural and 4 rejections, plus 5 unit/integration tests. All green. Run
cargo test.
Passing today: functions, impl methods, trait impls (formatting traits and
From), structs, enums (C-like and data-carrying), Option/Result with
?, slice iterators (iter/iter_mut/enumerate/zip/chunks_exact/
chunks_exact_mut/windows), borrowed slices as values and return types,
let/let mut, the full integer
and float operator set at exact widths, as casts, if/while/loop/for,
match including patterns that bind, Vec/slices/arrays, type aliases
(including generic ones), function-typed parameters (impl Fn(A) -> B),
multi-file input, #[cfg] evaluation, and println!/format! with {},
{:?}, {:x}, {:b}, positional and inline-named arguments, and
zero/space padding.
Why this exists
We tried tarekwasfy01/Code-Transpiler,
which advertises rust as a source language, on the base16ct crate. It emits
empty files and exits 0. The full investigation is in findings/
and is published at
https://rickub.com/nandi/code-transpiler-rust-frontend-findings
The decisive finding, and the reason this is a new project rather than a patch:
its Universal AST cannot represent Rust. defaultSemanticTypeContract() in
internal/backend/semantic_program.go:85 is hardcoded to
numeric: binary64, integer_width: unknown, truth: r_compatible,
ownership: unknown, index_base: 1
and semantic_document.go:1014 validates that every contract equals exactly
that, while typed_operation.go:46 rejects any value model that is not
tagged_dynamic_binary64. There is no integer width and no ownership in the
model at all. Code like base16ct's constant-time decoder —
ret += (((0x2fi16 - byte) & (byte - 0x3a)) >> 8) & (byte - 47);
— depends on exact 16-bit signed wrapping and arithmetic shift. Lowering that
into a 1-indexed dynamic float64 model produces silently wrong answers. So the
first rule of this project is the one that codebase broke:
Never approximate a semantic you cannot represent. Fail loudly instead.
src/ty.rs already does this: i128/u128 are rejected with a reason rather
than widened or truncated.
Architecture
Rust source ──syn──> syn AST ──lower──> Nim source ──nim c──> binary
The frontend is syn, deliberately. Hand-rolling a Rust grammar is how the
other project went wrong; a correct parser is not the interesting part of this
problem. The interesting part is the lowering, which is where all the work goes.
Planned modules:
| file | role | state |
|---|---|---|
src/ty.rs |
Rust type → Nim type, exact widths, explicit rejections | written |
src/lower.rs |
items, statements, expressions → Nim | written |
src/fmt.rs |
println!/format! format-string handling |
written |
src/prelude.nim |
Option/Result/panic/Display/Debug runtime |
written |
src/main.rs |
CLI: rustnim <in.rs> -o <out.nim> |
written |
tests/differential.rs |
the runner described below | written |
Enums, Option and Result
A C-like enum becomes a plain Nim enum, which compares, orders and
case-checks the way Rust's does. A data-carrying enum becomes a Nim object
variant — a discriminant enum plus one branch per variant — which is the same
shape the prelude already uses for Option and Result. Nim requires the
branches of a variant object to have distinct field names, so each payload
field is prefixed with its variant.
match takes one of two forms. Arms that neither bind nor destructure become
a Nim case, which is exhaustiveness-checked the way Rust's is. Arms that do
bind become an if/elif chain with the bindings emitted as lets, because
Nim's case cannot destructure. The chain always ends in an arm that panics:
Rust proved it unreachable, but Nim cannot see that, and leaving the chain
open would silently fall through instead.
Ok, Err and Some are emitted with their full type arguments
(rsOk[T, E](v)), because Nim cannot infer E from an Ok(v) alone. That is
why the expected type has to reach a match arm as well as a let.
? expands to statements — a temporary, a discriminant test, and an early
return — which are emitted ahead of the line being built. Rust inserts a
From::from on the error there; we accept only the case where the two error
types already agree, rather than assume a conversion is the identity. ? in a
while condition is rejected: the early return would run once before the
loop rather than on each iteration.
Trait impls
A Display impl becomes proc rsDisplay(self: T): string. Rust's Formatter
is a sink and the observable result of {} is exactly the bytes written into
it, so every write through the formatter produces that string and the existing
match/trailing-expression machinery assembles it. A fmt body that does
anything else with the formatter — padding, precision, debug_struct — is
rejected, because those change the output and this model does not carry them.
Debug, LowerHex, UpperHex, Binary and Octal work the same way.
impl From<A> for B becomes a conversion proc that .into() resolves
through. A marker trait with no items generates nothing: we do not model trait
resolution anywhere, so there is nothing for it to affect; a use that actually
needed the trait (a dyn, a bound) is rejected where it appears. Any other
trait impl is rejected.
Methods are keyed by (receiver type, name), not by name alone — two types
may define the same method, and Nim tells them apart by overload resolution on
the first parameter.
fmt::Error is not the same type as a crate's own Error. Collapsing a
qualified path to its last segment merged them, which was a real soundness
bug; core::fmt's types are now recognised by their qualified name.
Slice iterators are resolved to one index loop
Rust's slice iterators are lazy and compose. Nim's for is over one sequence,
so a chain of adaptors is resolved into a small IR and emitted as a single
index loop in which each binding is an lvalue into the original container.
That is what makes *d = v through iter_mut() write back to the caller's
slice instead of to a copy, and what lets chunks_exact(2) hand out a window
that indexes straight into the source with an offset.
Only adaptors with an exact index-loop equivalent are accepted. map,
filter and take_while are rejected rather than partially honoured:
silently dropping an adaptor would change which elements the loop visits.
zip stops at the shorter side, as Rust's does — that is a test, not an
assumption (tests/cases/023).
Borrowed slices are views, not copies
&[T] is a borrow. Nim's experimental view types model exactly that,
including returning one from a proc: writing through the returned view is
visible in the original buffer. That was probed against Nim 2.2.4 before being
relied on, because copying into a seq would print the right bytes while
silently changing aliasing.
s.get(a..b) is the one place this leaks. It is an Option<&[T]>, and Nim
cannot put a view inside an object, so there is no value to hand back. Instead
the view and its validity condition travel together through ok_or until a
? or unwrap resolves them into a bounds check plus a binding. Keeping such
an Option in a variable is rejected with a message saying so.
Declaration order
Rust has no declaration-before-use rule and Nim does, so every proc is
forward-declared between the type definitions and the bodies. Reordering the
input instead would not handle mutual recursion.
Type propagation is load-bearing
Rust infers an unsuffixed integer literal's type from context and falls back
to i32; Nim falls back to 64-bit int. So lower.rs threads an expected
type down through every expression — into let annotations, call arguments,
match patterns, compound assignments and both operands of a binary — and
annotates every binding it emits. Without that, let x: u8 = 200; x + 100
means two different things in the two languages. With it, a width the lowering
gets wrong becomes a Nim compile error (a loud failure, reported by the
runner) rather than a wrong answer.
Mapping decisions made so far
- Integers: exact width.
i32→int32,usize→uint, etc.i128/u128
rejected. - Indexing: both 0-based. Direct.
&T→ plain value.&mut T→var Tparameter.&[T]→openArray[T]in parameter position,seq[T]when owned.
Nim::owned()performs that conversion.- Ownership/borrowck: ignored. Nim is GC'd; for safe Rust this is sound.
Option/Result→ object variants in the prelude.match→ Nimcasewhere the arms are simple,if/elifwhen arms have
guards or bindings.- Rust's expression-orientation maps well: Nim
if/caseare expressions
too, and a proc's trailing expression is its return value.
Settled empirically (Nim 2.2.4 vs rustc 1.98.1, both run)
-
Nim's
shron a signed integer is arithmetic, matching Rust.
int16(-256) shr 8=-1in Nim;(-256i16) >> 8=-1in Rust.
base16ct's decoder depends on this, so it maps directly with no helper. -
Nim's fixed-width unsigned arithmetic wraps silently, matching Rust's
wrapping_*.uint8(200) + 100=44in Nim;200u8.wrapping_add(100)
=44in Rust. Sowrapping_addon an unsigned type is just+. -
We model rustc's debug profile. Rust debug builds panic on signed
integer overflow; Nim's default build raisesOverflowDefecton it. Those
are the matching pair, so the runner invokesrustcwithout-Oandnim cwith its defaults, andtests/cases/016pins the behaviour. A Rust
panic exits 101 where a Nim Defect exits 1, so every generated module ends
with a handler that maps one to the other — otherwise the runner's
exit-status comparison would be vacuous.wrapping_*is therefore an
explicit operation on both sides: unsigned maps to the bare operator (item
2), signed is routed through the unsigned view of the same width. -
charround-trips. Rustchar→ NimRune, confirmed for ASCII and
non-ASCII scalars in both{}and{:?}, and acrossas u32
(tests/cases/014).
Still open
checked_*andsaturating_*are not mapped yet; they are currently
rejected as unsupported methods rather than approximated.- Generics (type and const parameters), closures,
unsafe, and trait impls
other than the formatting traits andFromare rejected with a reason.
Lifetime parameters are not a rejection: they carry no runtime meaning
and Nim is GC'd, sofn encode<'a>(..)lowers fine. - Float formatting matches Rust for ordinary values and for
inf/NaN, but
the exponent-form thresholds have only been checked at1e21. - Flattening several files into one module can collide a crate's own
type Result<T>with the builtinResult<T, E>. Rust kept them apart by
module; we tell them apart by arity. That is a real difference from Rust's
resolution and would need proper module scoping to fix.
Testing: differential, not golden
The bar is behavioural equivalence with rustc, not that the output looks
plausible. For each case in tests/cases/:
rustc case.rs && ./case > expected
rustnim case.rs -o case.nim && nim c -r case.nim > actual
diff expected actual
A case only counts as passing when both binaries build and produce identical
stdout and exit with the same status.
tests/differential.rs implements this, and checks each stage separately so a
failure says where it went wrong: rustnim, rustc, nim, or diff. Three
guards exist specifically because of how the other transpiler failed:
rustnimexiting 0 while writing no output file is a failure.rustnimexiting 0 while writing an empty output file is a failure.- An empty corpus is a failure, so the runner cannot pass by finding
nothing to do.
All three have been verified by deliberately breaking the transpiler and
confirming the runner goes red.
Cases carry directives in leading //@ comments:
| directive | meaning |
|---|---|
//@ reject: <substring> |
rustnim must fail, with this in its message |
//@ skip: <reason> |
not run; reported as skipped |
//@ args: <argv> |
passed to both binaries |
//@ stdin: <line> |
fed to both binaries |
reject cases are how the "fail loudly" rule is tested rather than merely
stated: 900–904 pin the rejections of i128, an unmapped standard-library
method, a float→int cast, an unimplemented format spec, and a closure.
Run one case with RUSTNIM_CASE=005 cargo test --test differential -- --nocapture. Nim is found at .nim-toolchain/bin/nim in the repository root
or any parent, or via RUSTNIM_NIM.
Toolchain
rustc/cargo1.98.1 — system.- Nim 2.2.4 — vendored at
.nim-toolchain/(gitignored; downloaded from
nim-lang.org, not installed system-wide). Binary:.nim-toolchain/bin/nim.
Milestone 1
Transpile base16ct 1.0.0 — the crate the other transpiler failed on — and
have its decoder produce byte-identical output to the Rust original.
The decoder is reached. tests/cases/026-base16ct-crate/ transpiles
base16ct's error.rs and mixed.rs byte-for-byte as published on
crates.io — verified with cmp, not by eye — together with lib.rs's
decoded_len, encoded_len and decode_inner verbatim, and its output is
byte-identical to rustc's:
mixed-l ok abcd1234 len=4 lower, upper and mixed hex all decode
mixed-u ok abcd1234 len=4
mixed-m ok abcd1234 len=4
edge ok 00ff7f80 len=4
oddlen err InvalidLength / invalid Base16 length <- Debug and Display
bad err InvalidEncoding / invalid Base16 encoding
empty ok len=0
short-dst err InvalidLength / invalid Base16 length
decode_inner goes through as written: dst.get_mut(..decoded_len(src)?),
src.chunks_exact(2).zip(dst.iter_mut()), *dst = byte as u8, and the
returned &'a [u8] view into the caller's buffer. The Display line in that
output comes from the crate's own impl fmt::Display for Error.
Still to do for the whole crate
lower.rs/upper.rs:encodeitself lowers, but the same file defines
encode_str, whose body is a closure over anunsafeblock. Both
are unimplemented, and a file is all-or-nothing, so neither module is in the
case yet.display.rs:HexDisplay<'a>(pub &'a [u8])is a tuple struct holding a
borrowed slice. A struct field of view type is what Nim's view types do
not allow, which is the same wall asOption<&[T]>.- The
allochalf (decode_vec,encode_string) needs--cfg feature=alloc
and thenString::from_utf8_unchecked, i.e.unsafeagain.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 |
|