Preface
In many ways, this is more than just a passion project; it's a journey through the realms of curiosity and perseverance. While at times it might seem like an exercise in futility, this project and the subsequent documentation of my adventures in its pursuit serve as a testament to the possibility of completion, not only for myself but for all the fellow procrastinators out there.
Esoteric programming languages have always held a particular fascination for me despite the absence of formal training in computer science. This lack, perhaps paradoxically, heightened my interest in implementing these languages. However, attempting to construct languages based on tutorials or delving into The Dragon Book presented challenges due to my unfamiliarity with both C and C++, which are considered the premier programming languages for such endeavors.
The turning point came with the discovery of Rust and the associated The Rust Programming Language Book, affectionately known as The Book in the community. This marked the moment I felt ready to take on a task as significant as creating an interpreter. While much has been written about the merits (and demerits) of using Rust as a backend for programming languages, most of this information was beyond my current understanding. Notably, the Rust community has successfully implemented various languages, such as Rhai, Kind, and Gleam, proving its versatility. For a hobbyist like me, Rust provided the perfect foundation to realize my project.
Now, why Brainf**k[^note]? Firstly, it's amusing; the name alone is sufficient to capture people's attention. More importantly, it's a simple yet expressive language. With only eight instructions, it discards many other useful features, making it an ideal testbed where someone like me can build, test, iterate, and repeat until the end of time. While a Brainf**k interpreter in Rust is not a novel idea and has been done before, the novelty lies in the fact that I hadn't done it, and therein lies the rub.
In conclusion, I wish to express my gratitude to a few individuals.
- My very patient wife and two boisterous daughters, who not only endured my brainstorming sessions but also occasionally tolerated my absence during this project.
- Tris Oaten of Lost Terminal and No Boilerplate fame, among other things. His Rust evangelism kept my interest in Rust alive, and his life lesson videos played a pivotal role in keeping me on track.
[^note] I am censoring for the sake of propriety, not because I have any issues with cursing.
Introduction
BrainFoamKit, or BFK as I like to call it, is a project that aims to implement a brainf**k, (or BF) interpreter in Rust. To make things easier for myself, and to keep up with the times, I have added one more instruction However, it's not JUST an interpreter. The broader scope aim of this project is to implement a complete, if poorly designed, and functional Virtual Machine (the BFKVM) that can interpret the instructions and allow for us to take a cross-section look as it executes the BFK program.
For this purpose, the project has three distinct parts:
brainfoamkit_lib, a library that implements theBFKVMand the interpreter forBFK.bfkrun, a binary that can be used to run programs written in eitherBForBFKdialects.bfkview, a TUI application with a (hopefully) intutive interface that lets you step through BF[K] programs.
Rationale
Brainf**k is an interesting esoteric language. It is turing complete and can theoretically be used as a general purpose programming language. However, it has only 8 individual symbols that are used to instruct the interpreter. This makes it both fun and challenging to implement.
While several C and C++ interpreters for Brainf**k exist, I believe that it is particularly well suited for implementation in Rust due the combination of memory-safety, speed and zero-cost abstractions. Additionally, the interpreter is expected to be non-trivial in complexity while still only scratching the surface of the features Rust has to offer. Thus, it provides an excellent educational opportunity for someone trying to learn Rust.
Implementation Details
Briefly, the interpreter is implemented as a Virtual Machine on top of the existing Rust runtime. This frees us from
low-level hardware constraints, allowing us to focus on the core of the program. The language remains focused on Byte-level operations and the ASCII code.
More details regarding the implementation, including an EBNF grammar and other design tradeoffs can be found in
the language reference pages for the original BF Specification and the BFK dialect.
(Planned) Features
- A complete brainfuck interpreter capable of ingesting a brainfuck program and behaving appropriately
- A modular system for the said interpreter, allowing for extensions and modifications
- A configurable brainfuck virtual machine to interpret the programs.
- A fully capable TUI to visualize and step through a brainfuck program
Current Status
- Implement basic building blocks for the Virtual Machine
- Implement the Virtual Machine to run the code
- Implement a parser for parsing the input program
- Design the TUI for the visualizer
- Implement the TUI with the Virtual Machine and parser
Progress for the project can be tracked on the Github Issues and the Github Project pages.
Contributing
See the Contributing for details on how to contribute to the project.
You can contribute to the project through GitPod.
Code of Conduct
This project is governed by the Contributor Code of Conduct Covenant. Details are outlined in the CODE OF CONDUCT.
Getting Started
Installation
The software can be installed in different ways, depending on your taste:
Cargo Install
You can install it directly from crates.io using cargo:
cargo install brainfoamkit
Cargo Binaries
You can also use the excellent cargo-binstall tool to install the binaries directly from the repository:
cargo install cargo-binstall
cargo binstall brainfoamkit
Manual Installation
You can also install the binaries manually by downloading the appropriate binaries from the releases page and placing them in your $PATH.
Usage
bfkrun
bfkrun is the main binary that can be used to run programs written in either BF or BFK dialects.
bfkrun accepts both strings and files as input.
# Use a direct input string
bfkrun --input "+[-->-[>>+>-----<<]<--<---]>-.>>>+.>>..+++[.>]<<<<.+++.------.<<-.>>>>+."
#> Hello, World!
# Use a file as input
# Create a file with the program
echo "+[-->-[>>+>-----<<]<--<---]>-.>>>+.>>..+++[.>]<<<<.+++.------.<<-.>>>>+." > hello_world.bf
# Run the program
bfkrun --file hello_world.bf
#> Hello, World!
bfkview
bfkview is a TUI application with a (hopefully) intutive interface that lets you step through BF[K] programs.
Detailed instructions coming soon.