<!--
SPDX-FileCopyrightText: 2023 - 2024 Ali Sajid Imami
SPDX-License-Identifier: Apache-2.0
SPDX-License-Identifier: MIT
-->
# Introduction
[](https://github.com/AliSajid/BrainFoamKit/actions/workflows/ci.yaml)
`BrainFoamKit`, or `BFK` as I like to call it, is a project that aims to implement a [brainf**k, (or BF)](https://esolangs.org/wiki/Brainfuck) 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:
1. `brainfoamkit_lib`, a library that implements the `BFKVM` and the interpreter for `BFK`.
2. `bfkrun`, a binary that can be used to run programs written in either `BF` or `BFK` dialects.
3. `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](./language_reference/README.md) and the [`BFK` dialect](./language_changes/README.md).
## (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](https://github.com/AliSajid/BrainFoamKit/issues) and
the [Github Project](https://github.com/users/AliSajid/projects/1) pages.
## Contributing
See the [Contributing](CONTRIBUTING.md) for details on how to contribute to the project.
You can contribute to the project through [GitPod](https://gitpod.io).
[](https://gitpod.io/#AliSajid/brainfoamkit)
## Code of Conduct
This project is governed by the Contributor Code of Conduct Covenant. Details are outlined in
the [CODE OF CONDUCT](CODE_OF_CONDUCT.md).