{"id":19125635,"url":"https://github.com/dmitmel/brainwhat","last_synced_at":"2025-05-05T20:15:39.797Z","repository":{"id":52305190,"uuid":"141812827","full_name":"dmitmel/brainwhat","owner":"dmitmel","description":"A fast optimizing Brainfuck interpreter written in pure Rust","archived":false,"fork":false,"pushed_at":"2021-04-17T16:01:55.000Z","size":48,"stargazers_count":18,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-05T20:15:35.560Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dmitmel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-21T13:00:17.000Z","updated_at":"2023-11-13T14:33:05.000Z","dependencies_parsed_at":"2022-09-06T08:40:13.112Z","dependency_job_id":null,"html_url":"https://github.com/dmitmel/brainwhat","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitmel%2Fbrainwhat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitmel%2Fbrainwhat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitmel%2Fbrainwhat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dmitmel%2Fbrainwhat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dmitmel","download_url":"https://codeload.github.com/dmitmel/brainwhat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252569648,"owners_count":21769517,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["brainfuck","brainfuck-interpreter","esoteric-language","interpreter","language","rust"],"created_at":"2024-11-09T05:36:14.925Z","updated_at":"2025-05-05T20:15:39.778Z","avatar_url":"https://github.com/dmitmel.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# brainwhat\n\n[![CI Status](https://github.com/dmitmel/brainwhat/workflows/CI/badge.svg)](https://github.com/dmitmel/brainwhat/actions?query=workflow:CI)\n\n\u003e A fast optimizing Brainfuck interpreter written in pure Rust\n\n## What is `brainwhat`?\n\n\u003e `brainwhat` is a fast optimizing [Brainfuck](#what-is-brainfuck) interpreter written in pure [Rust](https://www.rust-lang.org/)\n\n**fast** – Rust is a systems programming language, so it compiles to very fast native binaries.\n\n**optimizing** – Brainfuck code is first parsed to a [list of instructions](https://en.wikipedia.org/wiki/Intermediate_representation), then [optimized](#optimizations) and after that these instructions are passed to the **interpreter**.\n\n**interpreter** – it doesn't compile Brainfuck to another language, instead, it executes program directly.\n\n## What is Brainfuck?\n\n**Brainfuck** is an [esoteric programming language](https://en.wikipedia.org/wiki/Esoteric_programming_language) created by [Urban Müller](https://en.wikipedia.org/wiki/Brainfuck#History). It is not intended for practical use, but to challenge programmers. Despite its extreme minimalism, it is [Turing complete](https://en.wikipedia.org/wiki/Turing_completeness), so **it can solve any computation problem** with enough memory and time.\n\nBrainfuck operates on an array of memory cells, where each cell is initially set to zero. Also there's a pointer, initially set to the first memory cell. Brainfuck has _**eight**_ commands (all other characters are ignored, so they can be used as comments):\n\n| Command         | C equivalent                                                           | Description                                                   |\n| --------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------- |\n| _Program start_ | `int ptr = 0;`\u003cbr\u003e`char arr[30000];`\u003cbr\u003e`memset(arr, 0, sizeof(arr));` |                                                               |\n| `\u003e`             | `ptr++;`                                                               | Move the pointer to the right                                 |\n| `\u003c`             | `ptr--;`                                                               | Move the pointer to the left                                  |\n| `+`             | `arr[ptr]++;`                                                          | Increment value in the current cell                           |\n| `-`             | `arr[ptr]--;`                                                          | Decrement value in the current cell                           |\n| `.`             | `putchar(arr[ptr]);`                                                   | Print value in the current cell as an ASCII character         |\n| `,`             | `arr[ptr] = getchar();`                                                | Read a character and put its ASCII value in the current cell  |\n| `[`             | `while (arr[ptr]) {`                                                   | Jump past the matching `]` if the current cell is zero        |\n| `]`             | `}`                                                                    | Jump back to the matching `[` if the current cell is not zero |\n\n_For more information, check out [Wikipedia](https://en.wikipedia.org/wiki/Brainfuck), [Esolangs.org](https://esolangs.org/wiki/Brainfuck) and\n[BrainFuck Programming Tutorial](https://gist.github.com/roachhd/dce54bec8ba55fb17d3a)._\n\n## Project goals\n\nThis project should:\n\n1.  have code that is easy to read for beginners (who already know [the concepts of Rust](https://doc.rust-lang.org/book/second-edition/index.html))\n2.  not sacrifice readability for performance (thanks to the _magic_ of the Rust compiler)\n3.  show that (safe) Rust is a really fast language\n4.  be at least comparable to optimizing brainfuck interpreters written in C (e.g. [bff4](http://mazonka.com/brainf/)), but being faster than them would be nice too!\n\n## Installation\n\n```\ncargo install --git https://github.com/dmitmel/brainwhat\n```\n\n## Usage\n\nAs a command-line tool:\n\n```bash\nbrainwhat path/to/program.b\nbrainwhat \u003c path/to/program.b\n```\n\nAs a library (e.g. for [generating Brainfuck programs using AI](http://www.primaryobjects.com/2013/01/27/using-artificial-intelligence-to-write-self-modifying-improving-programs/)):\n\n```rust\nextern crate brainwhat;\n\n// this program prints \"hi!\"\nlet code = \"\u003e+++++[-\u003c+++\u003e\u003e++++++\u003e++\u003c\u003c]\u003c[-\u003e+++++++\u003c]\u003e-.+.\u003e+++.\u003e.\";\nlet code_chars = code.chars().collect::\u003cVec\u003cchar\u003e\u003e();\n// 4 memory cells is enough for this program\nlet memory_size = 4;\n\nlet parsed_program = brainwhat::parse(\u0026code_chars)?;\nlet optimized_program = brainwhat::optimize(\u0026parsed_program)?;\nlet mut interpreter = brainwhat::Interpreter::new(memory_size);\ninterpreter.run(\u0026optimized_program)?;\n```\n\n### Implementation details\n\n- The memory is constrained to 65,536 cells (64 KiB), although size of memory can be changed when using this interpreter as library.\n- The interpreter will [panic](https://doc.rust-lang.org/std/macro.panic.html) on under- or overflows when moving the pointer.\n- Cells have size of 1 byte.\n- Addition and subtraction can over- and underflow.\n- If EOF is reached when executing read (`,`) instruction, current cell will be set to zero.\n\n## Benchmarks\n\n**Brainfuck program:** DBFI (Brainfuck self-interpreter) which runs DBFI which runs simple program which prints `hello123`\n\n**Baseline implementations:** [`bff`](https://github.com/apankrat/bff) and [`bff4`](http://mazonka.com/brainf/) (with linear optimizations turned off)\n\n**Hardware:** _13-inch Early 2015 MacBook Pro_ with _Intel Core i7 @ 3.1 GHz_.\n\n```\nBenchmark #1: bin/bff bench_prog \u003c bench_input\n  Time (mean ± σ):     298.3 ms ±   4.0 ms    [User: 293.3 ms, System: 2.6 ms]\n  Range (min … max):   292.0 ms … 303.8 ms\n\nBenchmark #2: bin/bff4 \u003c bench_bff4_input\n  Time (mean ± σ):     247.9 ms ±   4.5 ms    [User: 242.7 ms, System: 2.8 ms]\n  Range (min … max):   244.3 ms … 259.3 ms\n\nBenchmark #3: bin/brainwhat bench_prog \u003c bench_input\n  Time (mean ± σ):     372.4 ms ±   7.1 ms    [User: 367.1 ms, System: 2.9 ms]\n  Range (min … max):   364.3 ms … 383.2 ms\n\nSummary\n  'bin/bff4 \u003c bench_bff4_input' ran\n    1.20x faster than 'bin/bff bench_prog \u003c bench_input'\n    1.50x faster than 'bin/brainwhat bench_prog \u003c bench_input'\n```\n\n## Optimizations\n\nThese are currently implemented optimizations, but I'm [planning](#todo) to add more.\n\n### 1. Instruction stacking\n\nSome instructions (`+`, `-`, `\u003e`, `\u003c`) are stackable, meaning that they can be merged into one instruction:\n\n```\n+++++ \u003e\u003e\u003e ------- \u003c\u003c\u003c\u003c\u003c\u003c -\u003e [Add(5), Move(3), Add(-7), Move(-6)]\n12345 123 1234567 123456 \u003c-- instruction counts\n```\n\n### 2. Loops\n\nAll loops are linked when parsing program, so interpreter doesn't have to search matching brackets at runtime (this optimization makes interpreter really fast!!!):\n\n```\n   __                            ____________________________\n  /  \\   \u003c------ loops ------\u003e  /                            \\\n |    |                        |                              |\n+[ ,. ] -\u003e [Add(1), JumpIfZero(4), Read, Print, JumpIfNonZero(1)]\n01 23 4 \u003c-- instruction addresses\n```\n\n## TODO\n\n- Documentation\n- CLI with different options (e.g. memory/cell size, behavior on overflows etc)\n- Different memory tapes (e.g. dynamic, finite etc)\n- More optimizations\n- Better handling of errors (i.e. print where the error has occurred)\n- [Visualizer](https://fatiherikli.github.io/brainfuck-visualizer/) or [debugger](https://www.iamcal.com/misc/bf_debug/)\n- More Brainfuck dialects (maybe)\n\n## Contribute\n\nPRs accepted.\n\n_I would really appreciate your help with [TODOs](#todo)!_\n\n## License\n\n[MIT](LICENSE) © [Dmytro Meleshko](https://github.com/dmitmel)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmitmel%2Fbrainwhat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdmitmel%2Fbrainwhat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdmitmel%2Fbrainwhat/lists"}