brainfuck interpreter
brainfuck
cli
rust
docs: cleaned up README and merged ROADMAP
+53
-54
+53
-18
README.md
+53
-18
README.md
···
1
1
# tachyon
2
2
a brainfuck interpreter written in rust.
3
3
4
-
## warning
5
-
my first rust project and my first interpreter.
6
-
bad code everywhere. you have been warned!
4
+
**warning!**: my first rust project and my first interpreter. bad code everywhere. you have been warned!
7
5
8
-
## features
9
-
- standard 30,000 byte tape with configurable length.
6
+
# features
7
+
- standard 30,000 byte tape with configurable length, pre-filled with 0s.
10
8
- **data pointer out-of-bounds behavior**: `error` (crash on bounds violation, default) or `wrap` (wrap around).
11
9
- **cell value out-of-bounds behavior**: `wrap` (wrapping 8-bit, default) or `error` (crash on overflow/underflow).
12
10
- **ascii i/o** (default) and **raw 8-bit numeric i/o** for input and output.
13
11
- **syntax diagnostics**: catches unmatched brackets before execution.
14
12
- unit tests covering instructions, loops, nesting, out-of-bounds behaviors, and i/o modes.
15
13
16
-
## building
14
+
# building
17
15
```bash
18
16
cargo build --release
19
17
```
20
18
21
-
## usage
19
+
# usage
22
20
```bash
23
21
./target/release/tachyon [OPTIONS] <PATH>
24
22
```
25
23
26
-
### options
27
-
| flag | description | values |
28
-
|------|-------------|--------|
29
-
| `-d`, `--data-oob` | data pointer out-of-bounds behavior | `error` (default), `wrap` |
30
-
| `-c`, `--cell-oob` | cell value out-of-bounds behavior | `wrap` (default), `error` |
31
-
| `-l`, `--length` | custom tape length | number (default: 30,000) |
32
-
| `-i`, `--input-type` | input mode | `ascii` (default), `raw` |
33
-
| `-o`, `--output-type` | output mode | `ascii` (default), `raw` |
34
-
| `-p`, `--delay` | instruction delay in ms (pairs well with tracing) | default: `0` |
35
-
| `-t`, `--tracing` | print tape state after every cycle | default: `false` |
36
-
37
24
run a brainfuck script:
38
25
```bash
39
26
./target/release/tachyon path/to/your/script.bf
···
53
40
```bash
54
41
./target/release/tachyon -c error script.bf
55
42
```
43
+
44
+
## options
45
+
| flag | description | values |
46
+
|------|-------------|--------|
47
+
| `-d`, `--data-oob` | data pointer out-of-bounds behavior | `error` (default), `wrap` |
48
+
| `-c`, `--cell-oob` | cell value out-of-bounds behavior | `wrap` (default), `error` |
49
+
| `-l`, `--length` | custom tape length | number (default: 30,000) |
50
+
| `-i`, `--input-type` | input mode | `ascii` (default), `raw` |
51
+
| `-o`, `--output-type` | output mode | `ascii` (default), `raw` |
52
+
| `-p`, `--delay` | instruction delay in ms (pairs well with tracing) | default: `0` |
53
+
| `-t`, `--tracing` | print tape state after every cycle | default: `false` |
54
+
55
+
# roadmap
56
+
features and milestones! nothing is guaranteed to happen. less of a roadmap and more a list of things i'd like to do
57
+
58
+
*this is all pretty overkill but im using this project as a way to learn stuff*
59
+
60
+
## cli
61
+
- [x] **argument parsing**: possibly switch to `clap` for nicer cli experience
62
+
- [x] **behavior flags**: overrides defaults in code (& possibly eventually in config?)
63
+
- set data pointer & cell value behavior
64
+
- set custom tape size
65
+
- [x] **8-bit i/o**: add 8-bit input/output option alongside ascii default
66
+
- [ ] **monomorphization**: implement input/output strategy for minor optimization gains
67
+
- [ ] **config file**: set up per-project config file for input & output
68
+
69
+
## out-of-bounds behaviors
70
+
- [x] **data pointer behavior**
71
+
- `error` (default): crash when moving past tape boundaries
72
+
- `wrap`: going out of bounds wraps around to start/beginning
73
+
- [x] **cell value behavior**
74
+
- `wrap` (default): 0 - 1 = 255
75
+
- `error`: crash on overflow/underflow
76
+
77
+
## better diagnostics
78
+
- [x] **errors**: switch to `miette` for richer error display with source snippets
79
+
- [x] **tracing**: cli flag to print state of vm/tape after every instruction
80
+
81
+
## visualization
82
+
- [ ] **real-time cell visualization**: tui showing tape being adjusted and data pointer moving in real time at adjustable speed
83
+
- [ ] **wasm**: compile to wasm for browser-based frontend?
84
+
85
+
## debugging
86
+
- [ ] **step debugger**: REPL-style debugger with breakpoints, cell inspection, and instruction stepping
87
+
88
+
## maintenance
89
+
- [ ] **comprehensive testing**: for all instructions and out-of-bounds behaviors
90
+
- [ ] **benchmarking**: use `criterion` to track performance?
-36
ROADMAP.md
-36
ROADMAP.md
···
1
-
# roadmap
2
-
features and milestones! nothing is guaranteed to happen. less of a roadmap and more a list of things i'd like to do
3
-
4
-
*this is all pretty overkill but im using this project as a way to learn stuff*
5
-
6
-
## cli
7
-
- [x] **argument parsing**: possibly switch to `clap` for nicer cli experience
8
-
- [x] **behavior flags**: overrides defaults in code (& possibly eventually in config?)
9
-
- set data pointer & cell value behavior
10
-
- set custom tape size
11
-
- [x] **8-bit i/o**: add 8-bit input/output option alongside ascii default
12
-
- [ ] **monomorphization**: implement input/output strategy for minor optimization gains
13
-
- [ ] **config file**: set up per-project config file for input & output
14
-
15
-
## out-of-bounds behaviors
16
-
- [x] **data pointer behavior**
17
-
- `error` (default): crash when moving past tape boundaries
18
-
- `wrap`: going out of bounds wraps around to start/beginning
19
-
- [x] **cell value behavior**
20
-
- `wrap` (default): 0 - 1 = 255
21
-
- `error`: crash on overflow/underflow
22
-
23
-
## better diagnostics
24
-
- [x] **errors**: switch to `miette` for richer error display with source snippets
25
-
- [x] **tracing**: cli flag to print state of vm/tape after every instruction
26
-
27
-
## visualization
28
-
- [ ] **real-time cell visualization**: tui showing tape being adjusted and data pointer moving in real time at adjustable speed
29
-
- [ ] **wasm**: compile to wasm for browser-based frontend?
30
-
31
-
## debugging
32
-
- [ ] **step debugger**: REPL-style debugger with breakpoints, cell inspection, and instruction stepping
33
-
34
-
## maintenance
35
-
- [ ] **comprehensive testing**: for all instructions and out-of-bounds behaviors
36
-
- [ ] **benchmarking**: use `criterion` to track performance?