nandi/rustnim · README.md

⑂ 99b837678a29fedd20bb68a5117a6621d8d178b4

README.md · 114 lines · 4.8 KBmarkdown    Blame HistoryRaw
Add a README  nandithebull 1
3A Rust → Nim transpiler. It parses Rust with `syn` and emits Nim source that
4behaves the same way — same stdout, same exit status — when both are built and
7The rule the whole thing is organised around: **never approximate a semantic
8you cannot represent.** If a construct doesn't map, `rustnim` says so and exits
9non-zero. It never writes a file it can't stand behind.
11That rule comes from a real failure. We tried an existing transpiler that
12advertises Rust support on the `base16ct` crate; it emitted an empty file and
13exited 0. The write-up is in [`findings/`](findings/).
15## Build and run
18cargo build --release
19./target/release/rustnim input.rs -o out.nim
20nim c out.nim
23Several inputs are concatenated into one Nim module, in the order given — Nim
24has no per-file `mod`, so items are flattened and names must not collide:
27rustnim src/lib.rs src/error.rs --cfg feature=alloc -o crate.nim
30## What works
32Functions and `impl` methods, structs, enums (C-like and data-carrying),
33`Option`/`Result` with `?`, `let`/`let mut`, the integer and float operators at
34exact widths, `as` casts, `if`/`while`/`loop`/`for`, `match` including binding
35patterns, `Vec`/slices/arrays, type aliases, function-typed parameters
36(`impl Fn(A) -> B`), multi-file input, `#[cfg]`, and `println!`/`format!` with
37`{}`, `{:?}`, `{:x}`, `{:b}`, positional and inline-named arguments, and
38zero/space padding.
Correct the README where trait impls and iterators are listed as rejected  nandithebull 40Also: the formatting trait impls (`Display`, `Debug`, `LowerHex`, `UpperHex`,
41`Binary`, `Octal`) and `From`; and slice iterators — `iter`, `iter_mut`,
42`enumerate`, `zip`, `chunks_exact`, `chunks_exact_mut`, `windows` — resolved
43into a single index loop where each binding is an lvalue into the original
44container, so `*d = v` through `iter_mut()` reaches the caller's slice.
45Borrowed slices are views, not copies, including as return types.
Add display.rs and the alloc half: all of base16ct now goes through  nandithebull 47Closures and `unsafe` blocks, `&str` as a borrowed view rather than an owned
48copy, formatting impls whose `fmt` body writes repeatedly, and the
49`assert!`/`assert_eq!`/`debug_assert*` family. Modules: pass the crate root first and each further file after it,
Add closures and unsafe; base16ct's lower.rs and upper.rs go through  nandithebull 50and items are scoped by module, so `lower::decode` and `mixed::decode` stay
51
Correct the README where trait impls and iterators are listed as rejected  nandithebull 53Rejected with a reason, rather than guessed at: `i128`/`u128`, generics,
Add closures and unsafe; base16ct's lower.rs and upper.rs go through  nandithebull 54`move` closures, trait impls other than the ones above, iterator adaptors with
55no index-loop equivalent (`map`, `filter`, `take_while`), float→int casts, and
56any standard-library method that isn't mapped.
Correct the README where trait impls and iterators are listed as rejected  nandithebull 57
58## base16ct
Add display.rs and the alloc half: all of base16ct now goes through  nandithebull 60**It goes through.** `tests/cases/026-base16ct-crate/` transpiles every source
61file of base16ct 1.0.0 — `error.rs`, `lower.rs`, `upper.rs`, `mixed.rs`,
62`display.rs` — byte-for-byte as published on crates.io, plus `lib.rs`'s
63`decoded_len`, `encoded_len` and `decode_inner` verbatim, with the `alloc`
64half enabled. Decoding and encoding are byte-identical to rustc's, including
65`encode_str` (a closure over an `unsafe` block returning a borrowed `&str`
66view of the bytes just written) and `HexDisplay`, whose `UpperHex` impl writes
67once per byte into the formatter.
69That is the crate the transpiler in [`findings/`](findings/) emitted an empty
70file for, while exiting 0.
Add a README  nandithebull 71
Prove byte-identity for base16ct by enumerating whole input domains  nandithebull 72How strong is "byte-identical"? [`PROOF.md`](PROOF.md) answers that precisely:
73exhaustive over every two-byte decode input, every two-byte encode input and
74every single byte through `encode_str`/`HexDisplay`, plus a compositional
75argument for longer inputs and 20,000 pseudorandom cases attacking it.
76`cargo test --test proof` runs it — 151,463 cases, 9.1 MB of output, compared
77byte for byte.
Add a README  nandithebull 79
82
85The tests are differential, with rustc as the oracle. Each case in
86`tests/cases/` is compiled by rustc and run, transpiled and compiled by Nim and
87run, and the two stdouts and exit statuses must match. Building anything less
88than that — checking the Nim output "looks right", say — is how you end up
89shipping the bug in `findings/`. `rustnim` exiting 0 with a missing or empty
90output file is a hard failure, and so is an empty corpus.
92rustc is invoked without `-O` so debug-profile overflow checks are on, which is
93the matching pair for `nim c`'s defaults.
95Nim is found at `.nim-toolchain/bin/nim` in the repo root or any parent, or via
96`RUSTNIM_NIM`. Run a single case with:
99RUSTNIM_CASE=005 cargo test --test differential -- --nocapture
102
104| file | role |
105
106| `src/ty.rs` | Rust type → Nim type, exact widths, explicit rejections |
107| `src/lower.rs` | items, statements, expressions → Nim |
108| `src/fmt.rs` | `println!`/`format!` format strings |
109| `src/prelude.nim` | `Option`/`Result`, panic, `Display`/`Debug` runtime |
110| `tests/differential.rs` | the runner above |
112[`DESIGN.md`](DESIGN.md) has the reasoning: how each construct is mapped, what
113was settled by running both compilers rather than by reading docs, and what's
114still open.

Add a README b66da6b nandithebull 5h ago	1	# rustnim
	2
	3	A Rust → Nim transpiler. It parses Rust with `syn` and emits Nim source that
	4	behaves the same way — same stdout, same exit status — when both are built and
	5	run.
	6
	7	The rule the whole thing is organised around: **never approximate a semantic
	8	you cannot represent.** If a construct doesn't map, `rustnim` says so and exits
	9	non-zero. It never writes a file it can't stand behind.
	10
	11	That rule comes from a real failure. We tried an existing transpiler that
	12	advertises Rust support on the `base16ct` crate; it emitted an empty file and
	13	exited 0. The write-up is in [`findings/`](findings/).
	14
	15	## Build and run
	16
	17	```bash
	18	cargo build --release
	19	./target/release/rustnim input.rs -o out.nim
	20	nim c out.nim
	21	```
	22
	23	Several inputs are concatenated into one Nim module, in the order given — Nim
	24	has no per-file `mod`, so items are flattened and names must not collide:
	25
	26	```bash
	27	rustnim src/lib.rs src/error.rs --cfg feature=alloc -o crate.nim
	28	```
	29
	30	## What works
	31
	32	Functions and `impl` methods, structs, enums (C-like and data-carrying),
	33	`Option`/`Result` with `?`, `let`/`let mut`, the integer and float operators at
	34	exact widths, `as` casts, `if`/`while`/`loop`/`for`, `match` including binding
	35	patterns, `Vec`/slices/arrays, type aliases, function-typed parameters
	36	(`impl Fn(A) -> B`), multi-file input, `#[cfg]`, and `println!`/`format!` with
	37	`{}`, `{:?}`, `{:x}`, `{:b}`, positional and inline-named arguments, and
	38	zero/space padding.
	39
Correct the README where trait impls and iterators are listed as rejected 428f374 nandithebull 5h ago	40	Also: the formatting trait impls (`Display`, `Debug`, `LowerHex`, `UpperHex`,
	41	`Binary`, `Octal`) and `From`; and slice iterators — `iter`, `iter_mut`,
	42	`enumerate`, `zip`, `chunks_exact`, `chunks_exact_mut`, `windows` — resolved
	43	into a single index loop where each binding is an lvalue into the original
	44	container, so `*d = v` through `iter_mut()` reaches the caller's slice.
	45	Borrowed slices are views, not copies, including as return types.
	46
Add display.rs and the alloc half: all of base16ct now goes through afb2a6e nandithebull 4h ago	47	Closures and `unsafe` blocks, `&str` as a borrowed view rather than an owned
	48	copy, formatting impls whose `fmt` body writes repeatedly, and the
	49	`assert!`/`assert_eq!`/`debug_assert*` family. Modules: pass the crate root first and each further file after it,
Add closures and unsafe; base16ct's lower.rs and upper.rs go through 0a375d8 nandithebull 4h ago	50	and items are scoped by module, so `lower::decode` and `mixed::decode` stay
	51	distinct.
	52
Correct the README where trait impls and iterators are listed as rejected 428f374 nandithebull 5h ago	53	Rejected with a reason, rather than guessed at: `i128`/`u128`, generics,
Add closures and unsafe; base16ct's lower.rs and upper.rs go through 0a375d8 nandithebull 4h ago	54	`move` closures, trait impls other than the ones above, iterator adaptors with
	55	no index-loop equivalent (`map`, `filter`, `take_while`), float→int casts, and
	56	any standard-library method that isn't mapped.
Correct the README where trait impls and iterators are listed as rejected 428f374 nandithebull 5h ago	57
	58	## base16ct
	59
Add display.rs and the alloc half: all of base16ct now goes through afb2a6e nandithebull 4h ago	60	It goes through. `tests/cases/026-base16ct-crate/` transpiles every source
	61	file of base16ct 1.0.0 — `error.rs`, `lower.rs`, `upper.rs`, `mixed.rs`,
	62	`display.rs` — byte-for-byte as published on crates.io, plus `lib.rs`'s
	63	`decoded_len`, `encoded_len` and `decode_inner` verbatim, with the `alloc`
	64	half enabled. Decoding and encoding are byte-identical to rustc's, including
	65	`encode_str` (a closure over an `unsafe` block returning a borrowed `&str`
	66	view of the bytes just written) and `HexDisplay`, whose `UpperHex` impl writes
	67	once per byte into the formatter.
	68
	69	That is the crate the transpiler in [`findings/`](findings/) emitted an empty
	70	file for, while exiting 0.
Add a README b66da6b nandithebull 5h ago	71
Prove byte-identity for base16ct by enumerating whole input domains 99b8376 nandithebull 4h ago	72	How strong is "byte-identical"? [`PROOF.md`](PROOF.md) answers that precisely:
	73	exhaustive over every two-byte decode input, every two-byte encode input and
	74	every single byte through `encode_str`/`HexDisplay`, plus a compositional
	75	argument for longer inputs and 20,000 pseudorandom cases attacking it.
	76	`cargo test --test proof` runs it — 151,463 cases, 9.1 MB of output, compared
	77	byte for byte.
	78
Add a README b66da6b nandithebull 5h ago	79	## Tests
	80
	81	```bash
	82	cargo test
	83	```
	84
	85	The tests are differential, with rustc as the oracle. Each case in
	86	`tests/cases/` is compiled by rustc and run, transpiled and compiled by Nim and
	87	run, and the two stdouts and exit statuses must match. Building anything less
	88	than that — checking the Nim output "looks right", say — is how you end up
	89	shipping the bug in `findings/`. `rustnim` exiting 0 with a missing or empty
	90	output file is a hard failure, and so is an empty corpus.
	91
	92	rustc is invoked without `-O` so debug-profile overflow checks are on, which is
	93	the matching pair for `nim c`'s defaults.
	94
	95	Nim is found at `.nim-toolchain/bin/nim` in the repo root or any parent, or via
	96	`RUSTNIM_NIM`. Run a single case with:
	97
	98	```bash
	99	RUSTNIM_CASE=005 cargo test --test differential -- --nocapture
	100	```
	101
	102	## Layout
	103
	104	\| file \| role \|
	105	\|---\|---\|
	106	\| `src/ty.rs` \| Rust type → Nim type, exact widths, explicit rejections \|
	107	\| `src/lower.rs` \| items, statements, expressions → Nim \|
	108	\| `src/fmt.rs` \| `println!`/`format!` format strings \|
	109	\| `src/prelude.nim` \| `Option`/`Result`, panic, `Display`/`Debug` runtime \|
	110	\| `tests/differential.rs` \| the runner above \|
	111
	112	[`DESIGN.md`](DESIGN.md) has the reasoning: how each construct is mapped, what
	113	was settled by running both compilers rather than by reading docs, and what's
	114	still open.