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
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
//! Rust on CARDIAC.
//!
//! A program uses this crate for CARDIAC's card reader and teletype, `inp()` and `out()`, and for a few built-ins
//! that CARDIAC does its own way. The same program builds two ways:
//!
//! - `cargo run` builds it for your machine. `inp()` reads numbers from standard input, and `out()` prints them.
//! - `cargo cardiac run` builds it for CARDIAC with the rust-cardiac compiler and runs it on heartburn's `burn`.
//! `inp()` is the instruction INP, and `out()` is OUT.
//!
//! ```no_run
//! use cardiac::*;
//!
//! fn main() {
//! let n = inp();
//! for i in (0..=n).rev() {
//! out(i);
//! }
//! }
//! ```
//!
//! Given 5, both builds print 5 down to 0.
//!
//! A CARDIAC cell holds a sign and three digits, so every value is from -999 to 999. A program whose values stay in
//! that range prints the same numbers both ways. With overflow checks on, arithmetic that leaves the range panics on
//! CARDIAC. With them off, a cell keeps the last three digits.
//!
//! To build for CARDIAC, install the cargo subcommands with `cargo install cargo-cardiac`, then
//! `cargo cardiac new countdown` makes a package like the one above.
//!
//! The rest is at [lab.strangequery.com/rust-cardiac](https://lab.strangequery.com/rust-cardiac/): getting started,
//! what Rust works on CARDIAC, the compiler's messages, and the tools for running and debugging a program.
//!
//! Each function's documentation says what it is on CARDIAC, what it costs there and what it does with `cargo run`.
// On CARDIAC. The compiler turns each call into instructions; these bodies are never run. `inline(never)` keeps
// rustc from inlining them into the program, so the calls stay where the compiler can see them.
/// On CARDIAC: INP. Documented on the native version.
/// On CARDIAC: OUT. Documented on the native version.
/// On CARDIAC: HRS n. Documented on the native version.
/// On CARDIAC: an array the loader fills, at a label of its own. Documented on the native version.
/// Digit `k` of a value 0..=999: `k` = 0 is the hundreds, 1 the tens, 2 the units.
///
/// On CARDIAC it is the shift that keeps that digit, `SFT (k+1)3`, built for `k` and run: 5 cells, where the
/// same thing in Rust arithmetic costs about 9. Natively it is this body.
/// On CARDIAC: a jump into a row of `INP 00`. Documented on the native version.
/// On CARDIAC: a jump into a row of `ADD c`. Documented on the native version.
/// A `bool` for a flag kept in a cell and tested more than once: the same trues and falses, and on CARDIAC one
/// instruction less per test.
///
/// ```no_run
/// use cardiac::*;
///
/// fn main() {
/// let mut seen_zero: Flag = false.into();
/// loop {
/// let v = inp();
/// if v == 0 {
/// seen_zero = true.into();
/// }
/// if seen_zero.get() {
/// out(v);
/// }
/// }
/// }
/// ```
///
/// CARDIAC has one test, TAC: jump if the accumulator is negative. A `bool` is 0 or 1, as Rust promises, so testing
/// one kept in a cell is three instructions (load it, take away 1, TAC). A `Flag` holds -1 for false and 0 for
/// true, so testing it is two (load it, TAC): a cell and a step less each time, at the cost of one cell holding
/// -1, which a program needs once. `cargo cardiac build` says when a program's bools would be smaller as `Flag`s.
///
/// A condition tested where it is worked out (`if a < b`) is never kept in a cell, and needs no `Flag`.
;
/// On CARDIAC: `core::hint::assert_unchecked`. Documented on the native version.
///
/// # Safety
///
/// `condition` must hold.
pub unsafe
// Natively: standard input and output.
/// Reads the next card.
///
/// On CARDIAC this is INP, one instruction, which reads a card into memory. When the reader is empty, the machine
/// stops.
///
/// With `cargo run`, it reads the next number from standard input. Numbers are separated by spaces or new lines.
/// When there are none left, the program stops, as CARDIAC does. Anything that isn't a number from -999 to 999 stops
/// it with an error.
/// Outputs a value.
///
/// On CARDIAC this is OUT, one instruction, which sends a cell to the teletype.
///
/// With `cargo run`, it prints `v` on a line of its own. A value outside -999..=999 can't be on a card, so it
/// panics. Every panic with `cargo run` prints -999 first, which is what CARDIAC outputs when it panics. On CARDIAC
/// such a value never reaches `out()`: with overflow checks on, the arithmetic that made it panics, and with them
/// off, the cell keeps the last three digits.
/// Ends a phase of a program too big for CARDIAC's memory.
///
/// On CARDIAC this is HRS n: the machine stops for deck n, the next phase. The loader reads that phase's code in
/// over this one's, and the data stays where it is. A program in phases builds as `NAME.cqb`, `NAME.2.cqb` and so
/// on. Put `overlay()` in `main` where each phase ends, or turn on `auto-overlay` under
/// `[package.metadata.cardiac]` and the compiler places the phases itself.
///
/// With `cargo run`, it does nothing. The whole program is in memory, so one phase runs straight into the next.
/// An array of `N` values from the file `resources/NAME`, beside the package's `Cargo.toml`.
///
/// ```no_run
/// # use cardiac::*;
/// let key: [i16; 10] = load_resource("key");
/// ```
///
/// The file holds numbers separated by spaces or new lines, as the input does.
///
/// On CARDIAC the loader puts the values in memory with the program, so the array costs no code. Call it once, in
/// `main` and outside any loop, since the loader fills it once. The program may change the array afterwards.
///
/// With `cargo run`, the file is read when the program runs, so it can change between runs. It is found through
/// `CARGO_MANIFEST_DIR`, or the current directory when the program is run some other way. A missing file, a value
/// that isn't a card, or a count other than `N` stops the program with an error.
/// Reads `n` cards and drops them, as `for _ in 0..n { inp(); }` does. `n` is from 0 to 999.
///
/// On CARDIAC it jumps into a row of ten `INP 00`: once for the units of `n`, then through the whole row once for
/// each ten. A call takes 17 instructions, plus one for each card and two more for each ten, about 1.2 a card. The
/// loop takes 6 a card. The row is a routine put in once (27 cells), and each call costs 2 cells. A constant `n` of
/// 3 or less is that many `INP 00` in place. An `n` outside 0..=999 is undefined on CARDIAC.
///
/// With `cargo run`, it calls `inp()` `n` times. An `n` outside 0..=999 panics.
/// `n * c`, as `c` added up `n` times. `n` is from 0 to 99, and the product must be from -999 to 999.
///
/// On CARDIAC it jumps into a row of nine `ADD c`: once for the tens digit of `n`, then a shift, then again for the
/// units. A call takes about 27 instructions plus one for each addition, so `add_times(c, 37)` takes 37, where a loop
/// at 7 instructions an addition takes 263. The row is a routine put in once (34 cells), and each call costs 4 cells. A
/// constant `n` becomes `c * n` in place, with adds and a shift. An `n` or a product out of range is undefined on
/// CARDIAC.
///
/// With `cargo run`, it multiplies. An `n` or a product out of range panics.
/// Tells the compiler something about a value that it can't see for itself, such as a month always being from 1
/// to 12, so it can leave out checks it would otherwise need.
///
/// On CARDIAC it is `core::hint::assert_unchecked` and costs no code. With debug assertions on
/// (`debug-assertions = true` in the profile), CARDIAC checks it too, and a false assumption panics as `assert!`
/// does.
///
/// With `cargo run`, it is always checked. A false assumption panics and names the line that made it.
///
/// # Safety
///
/// `condition` must hold. On CARDIAC without debug assertions, a false assumption is undefined behaviour: the
/// checks it let the compiler drop are gone, and the program reads or computes whatever is there.
pub unsafe