Brainfuck-C 🧠

It is a fast, lightweight, and highly optimized esoteric programming language interpreter and code generator, inspired by the original language named BrainF*ck.

---

Quick Start

To get yourself started and try this program, use the following commands:

git clone https://github.com/arleydev0x101/brainfck-c
cd brainfck-c
make

# Ensure you have a valid .bf file to run, for example:
./bin/brainfk run main.bf

---

Pre-requisites

These are the following requirements:

Requirements	Description
GNU Make	For quickly compiling the software
gcc or clang	Our C Compiler
Git	For cloning/fetching the repository

In Linux and MacOS, most of these are already provided. If not, you can install them using your native package manager (e.g., sudo apt install build-essential git for Ubuntu/Debian, or brew install gcc make for MacOS).

For Windows, you have a few excellent options to get a POSIX-compatible environment:

Option 1: MSYS2 (Recommended for native Windows)

Download and install MSYS2. Open the MSYS2 MinGW x64 terminal and run the following commands using the pacman package manager:

pacman -Syu
pacman -S mingw-w64-ucrt-x86_64-gcc make git

# Check if gcc installed successfully
gcc --version

Option 2: WSL2 (Windows Subsystem for Linux)

If you use WSL2 (usually running Ubuntu or Debian), you can install the standard Linux build tools directly in your WSL terminal:

sudo apt update
sudo apt install build-essential git

# Check if gcc installed successfully
gcc --version

Option 3: Cygwin

Download and run the Cygwin Setup executable. During the installation process, when you reach the "Select Packages" screen, set the "View" dropdown to "Full" and search for the following packages to install:

• gcc-core (The C compiler)
• make (The GNU build tool)
• git (For cloning the repository)

---

Project Structure

The codebase is organized following standard C project conventions:

brainfuck-c/
├── include/            # C Header files (.h)
├── src/                # C Source files (.c)
├── samples/            # Example Brainfuck scripts
├── obj/                # Compiled object files (generated by Make)
├── bin/                # The final compiled executable (generated by Make)
└── Makefile            # Automated build instructions

---

Instructions & Usage

The compiled program acts as a multi-tool. You can pass it subcommands to either execute code (run) or generate it (gen).

# Compile the entire project
make

# Make the output executable (Linux/MacOS)
chmod +x bin/brainfk

1. The Interpreter (run)

Execute your Brainfuck scripts safely.

Syntax:

./bin/brainfk run <filename> [options]

Options:

• -c : Print the output as space-separated decimal values instead of ASCII characters.
• -s <number> : Add a custom ASCII character (provided by its decimal value) as a separator when using -c.
• -h : Print the help message.

Examples:

./bin/brainfk run main.bf                 # Standard execution
./bin/brainfk run main.bf -c              # Output decimal values
./bin/brainfk run main.bf -c -s 42        # Output decimals separated by '*' (ASCII 42)

2. The Code Generator (gen)

Translate normal text into highly optimized Brainfuck code. The generator utilizes a 5-Cell Heuristic Memory Map to find the mathematical shortest path for characters, resulting in highly compressed output.

Syntax:

# Provide text directly as arguments
./bin/brainfk gen Hello World!
./bin/brainfk gen "Hello World!"

# Or enter interactive mode by running without arguments
./bin/brainfk gen

---

Usage of Brainfck

These are the following symbols that you can use when writing BrainF*ck code:

Symbol	Description
<	Move to the left-side of the cell (previous cell).
>	Move to the right-side of the cell (next cell).
+	Increments 1 value in the current cell (val = (val + 1) % 256).
-	Decrements 1 value in the current cell (val = (val - 1) % 256).
.	Prints the current cell as an ASCII character.
,	Makes an input in the current cell.
[	Jumps forward to the command after the matching ] if the current cell is 0.
]	Jumps backward to the command after the matching [ if the current cell is NOT 0.

Note: The memory tape consists of 30,000 cells. Each cell is an 8-bit unsigned integer (unsigned char), meaning it mathematically holds values from 0 to 255. Any symbol or character that is not part of this table will be treated as a comment and safely ignored.

Example Generated Output

This is the highly optimized code our generator produces for the output "Hello World!":

++++++++++[>+++>+++++++>++++++++++>+++++++++++<<<<-]
>>++.
>+.
+++++++.
.
+++.
<<++.
>>---.
>---.
+++.
------.
--------.
>---.

---

Tips

Instead of manually highlighting and copying the generated output in your terminal, use terminal redirection to save it directly to a file:

# Write directly to a new file
./bin/brainfk gen "Hello World!" > sample.b

# Append to an existing file
./bin/brainfk gen "This is more text" >> sample.b

---

Troubleshooting

If this error occurs in your terminal when you use the make command:

make: *** [Makefile:x: all] Error 127

This usually means your C compiler wasn't found. Open the Makefile. If you installed clang instead of gcc, change the CC variable at the top of the file:

# Before
CC = gcc

# After
CC = clang

Then run make again.

---

Disclaimer

• Attribution: The Brainfuck esoteric programming language was originally designed by Urban Müller. This repository serves solely as an independent implementation.
• Educational Intent: The primary goal of this project is to write parsers, understand memory management, and expand upon learning the core of C programming fundamentals.
• Liability: This software is provided "as is", without warranty of any kind, express or implied. In no event shall the author, arleydev0x101, be liable for any claim, damages, or other liability arising from the use of this software.

For more info about BrainF*ck, check it out on Wikipedia.

Github: arleydev0x101