🧠 BetterBF (Better Brainf**k)

A modern, feature-rich extension of Brainf**k with functions, imports, conditionals, and more.

---

📖 Table of Contents

• Overview
• Features
• Installation
• Getting Started
• Syntax Reference
  • Classic Brainf**k Commands
  • Functions
  • Conditionals
  • Numeric Loops
  • Imports & Libraries
  • Comments
• Standard Library
• Compilation & Transpilation
• Examples
• License

---

🌟 Overview

BetterBF (.bbf) extends the classic Brainf**k (.bf) language with modern programming features while maintaining the minimalist spirit of the original. Write cleaner, more maintainable Brainf**k-style code with functions, imports, conditionals, and a standard library.

Why BetterBF?

• ✅ Functions & Namespaces: Organize your code into reusable components
• ✅ Import System: Share code across files and use system libraries
• ✅ Conditionals: Make decisions based on cell values
• ✅ Numeric Loops: Repeat operations without manual loop management
• ✅ Comments: Document your code clearly
• ✅ Standard Library: Built-in utilities for common tasks
• ✅ Transpilation: Compile to C or C++ for maximum performance
• ✅ Backward Compatible: All valid Brainf**k code works in BetterBF

---

🚀 Features

Feature	Description
Classic BF Support	Run any .bf file without modifications
Function Definitions	Create named, reusable code blocks
Nested Functions	Define functions within functions
Namespaced Imports	Import and organize external code
System Libraries	Use pre-built functionality from .bbfh headers
Conditionals	if(!=0) and if(==0) for branching logic
Numeric Loops	5[+] runs + five times
File Execution	Execute other files with $filename
C/C++ Transpilation	Convert to native code for performance

---

📦 Installation

Installation

Install any release from the releases tab, any .exe releases auto-add keys so you can just type bbf and it will work. The .deb packages also add the commands to source the executable.

Building from Source

# Clone the repository
git clone https://github.com/this-guy-git/BetterBF.git
cd BetterBF

# Build for Linux
make PLATFORM=linux

# Build for Windows
make PLATFORM=win

Prerequisites

• G++ compiler (MinGW for Windows)
• Make (for building)
• Standard C++11 or later

---

🎯 Getting Started

Your First BetterBF Program

Create a file called hello.bbf:

; This is a comment - prints "Hello"

10[+]      ; Set cell to 10 (newline)
72[+] .    ; Print 'H'
[-]        ; Clear cell
101[+] .   ; Print 'e'
[-]
108[+] .   ; Print 'l'
.          ; Print 'l' again
[-]
111[+] .   ; Print 'o'

Run It

Linux

# Using the interpreter
./bin/linux/bbf hello.bbf
# Or if you installed BBF
bbf hello.bbf

# Compile to native executable
./bin/linux/bbfcompiler hello.bbf -c hello
# Or if you installed BBF
bbfcompiler hello.bbf -c hello
./hello

Windows

# Using the interpreter
.\bin\win\bbf hello.bbf
# Or if you installed BBF
bbf hello.bbf

# Compile to native executable
.\bin\win\bbfcompiler hello.bbf -cw hello.exe
# Or if you installed BBF
bbfcompiler hello.bbf -cw hello.exe
.\hello

---

📚 Syntax Reference

Classic Brainf**k Commands

BetterBF supports all standard Brainf**k commands:

Command	Description
>	Move pointer right
<	Move pointer left
+	Increment current cell
-	Decrement current cell
.	Output current cell as ASCII
,	Input one character into current cell
[	Start loop (while cell != 0)
]	End loop

Functions

Define reusable code blocks with functions:

; Define a function
printHello{
    72[+] .    ; H
    [-]
    101[+] .   ; e
    [-]
    2[108[+] .] ; ll
    [-]
    111[+] .   ; o
}

; Call the function
printHello

Nested Functions

Functions can contain other functions:

IO{
    output{
        .
    }
    
    input{
        ,
    }
}

; Call nested function
IO.output

Conditionals

Execute code based on cell values:

; if(!=0){-} Execute if current cell is NOT zero
if(!=0){
    72[+] .    ; Print 'H'
}

; if(==0){+} Execute if current cell IS zero
if(==0){
    48[+] .    ; Print '0'
}

Example: Print different messages

+              ; Set cell to 1

if(!=0) {
    ; This executes because cell is 1
    89[+] .    ; Print 'Y'
    [-]
    101[+] .   ; Print 'e'
    [-]
    115[+] .   ; Print 's'
}

if(==0) {
    ; This doesn't execute
    78[+] .    ; Would print 'N'
    [-]
    111[+] .   ; Would print 'o'
}

Numeric Loops

Repeat operations a specific number of times:

; Syntax: N[commands]
5[+]           ; Increment 5 times (cell = 5)

10[>]       ; Move 10 from current cell to next cell

3[
    72[+] .    ; Print 'H' three times
    [-]
]

Imports & Libraries

User File Imports (#)

Import functions from other .bbf files:

; Import functions from mylib.bbf
#mylib.bbf

; Use functions from mylib
mylib.someFunction

System Library Imports (&)

Import from the standard library (.bbfh files in libs/ directory):

; Import the ASCII character library
&ASCIICHARS

; Use library functions
asciichars.print.H
asciichars.print.e
asciichars.print.l
asciichars.print.l
asciichars.print.o

Note: Library names are not case-insensitive. &asciichars, &AsciiChars, and &ASCIICHARS all work.

File Execution ($)

Execute another file completely (with fresh tape):

; Execute setup.bbf before continuing
$setup.bbf

; Continue with main program
72[+] .

Comments

Use semicolons for single-line comments:

; This is a comment
+              ; Increment cell

; Comments make your code readable!
5[+]           ; Add 5 to current cell

---

📚 Standard Library

BetterBF includes a standard library of useful functions:

ASCIICHARS - ASCII Character Printing

Print any ASCII character easily:

&asciichars

asciichars.print.H
asciichars.print.e
asciichars.print.l
asciichars.print.l
asciichars.print.o
asciichars.print.comma
asciichars.print.space
asciichars.print.W
asciichars.print.o
asciichars.print.r
asciichars.print.l
asciichars.print.d
asciichars.print.exclaim
asciichars.print.nl

Available characters include:

• Letters: A-Z, a-z
• Numbers: zero through nine
• Special: space, nl (newline), exclaim, question, comma, period, etc.
• Escape sequences: asciichars.esc.clear

CELL - Cell Manipulation

Utilities for working with memory cells:

&CELL

; Clear current cell
cell.edit.clearcurrent

; Clear all cells
cell.edit.clearall

; Print cell value
cell.read.printnext

; Check if cell is zero
cell.read.zerocheck

Available functions:

• cell.edit.* - Modify cells (clear, replace)
• cell.read.* - Read and inspect cells

---

🔧 Compilation & Transpilation

BetterBF includes a powerful compiler (bbfcompiler) that can transpile to C/C++ or compile directly to native executables.

Transpile to C++

# Output to stdout
./bbfcompiler hello.bbf -t

# Output to file
./bbfcompiler hello.bbf -t hello.cpp
./bbfcompiler hello.bbf -tpp hello.cpp

Transpile to C

./bbfcompiler hello.bbf -tc hello.c

Compile to Native Executable

# Linux executable
./bbfcompiler hello.bbf -c hello

# Windows executable
./bbfcompiler hello.bbf -cw hello.exe

# Compile C output
./bbfcompiler hello.bbf -cc hello

# Compile C++ output
./bbfcompiler hello.bbf -cpp hello

Compiler Options

Option	Shorthand	Description
--transpile	-t	Transpile to C++
--transpile-c	-tc	Transpile to C
--transpile-cpp	-tpp	Transpile to C++
--compile	-c	Compile to Linux executable (C++)
--compile-win	-cw	Compile to Windows executable
--compile-c	-cc	Compile to C executable
--compile-cpp	-cpp	Compile to C++ executable

---

💡 Examples

Example 1: Hello World with Functions

; hello_world.bbf
&ASCIICHARS

printHello {
    asciichars.print.H
    asciichars.print.e
    asciichars.print.l
    asciichars.print.l
    asciichars.print.o
}

printWorld {
    asciichars.print.W
    asciichars.print.o
    asciichars.print.r
    asciichars.print.l
    asciichars.print.d
}

; Main program
printHello
asciichars.print.space
printWorld
asciichars.print.exclaim
asciichars.print.nl

Example 2: Conditional Execution

; check_value.bbf
&ASCIICHARS

5[+]           ; Set cell to 5

if(!=0) {
    asciichars.print.N
    asciichars.print.o
    asciichars.print.n
    asciichars.print.minus
    asciichars.print.z
    asciichars.print.e
    asciichars.print.r
    asciichars.print.o
    asciichars.print.nl
}

[-]            ; Clear cell

if(==0) {
    asciichars.print.Z
    asciichars.print.e
    asciichars.print.r
    asciichars.print.o
    asciichars.print.nl
}

Example 3: Using Numeric Loops

; repeat.bbf
&ASCIICHARS

; Print "Hi! " three times
3[
    asciichars.print.H
    asciichars.print.i
    asciichars.print.exclaim
    asciichars.print.space
]

asciichars.print.nl

Example 4: Library Version Info

; version.bbf
&asciichars
&CELL

; Print library versions
asciichars.ver.print
cell.ver.print

---

📄 File Extensions

• .bbf - BetterBF source files
• .bf - Classic Brainf**k files (fully compatible)
• .bbfh - BetterBF header/library files (system libraries)

---

🔍 How It Works

Memory Model

BetterBF uses a tape of 30,000 cells, each holding an unsigned byte (0-255):

[0][0][0][0][0][0]...
 ^
 ptr (pointer starts at position 0)

• Cells wrap around at boundaries
• All cells initialized to 0
• Pointer starts at position 0

Function Resolution

Functions use dot notation for namespacing:

namespace.function.subfunction

• First part is the namespace (case-insensitive for imports)
• Subsequent parts are function names (case-sensitive)
• Functions are called without parentheses

---

🛠️ Advanced Usage

Creating Your Own Library

1. Create a .bbfh file with your functions:

; mylib.bbfh

print{
    greet{
        72[+] . [-]    ; H
        105[+] . [-]   ; i
    }

    farewell{
        66[+] . [-]    ; B
        121[+] . [-]   ; y
        101[+] . [-]   ; e
    }
}

2. Place it in the libs/ directory (for system libraries)

3. Import and use:

&MYLIB

mylib.print.greet
mylib.print.farewell

Combining Files

Use imports to create modular programs:

; utils.bbf
clearCell{
    [-]
}

increment5{
    5[+]
}

; main.bbf
#utils.bbf

utils.increment5
utils.clearCell

---

🐛 Debugging Tips

1. Use comments liberally - Document what each section does
2. Print intermediate values - Use . to see cell contents
3. Clear cells explicitly - Use [-] to prevent errors
4. Test functions individually - Build and test incrementally
5. Check pointer position - Remember where your pointer is

---

📝 License

BetterBF is licensed under the GNU General Public License v3.0.

Copyright (C) 2025  this guy Labs
https://github.com/this-guy-Labs

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

See the LICENSE file for details.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

---

🙏 Acknowledgments

• Inspired by the original Brainf**k language by Urban Müller
• Built with modern C++ for performance and portability
• Standard library designed for ease of use

---

📧 Contact

this guy Labs
GitHub: @this-guy-git

Email: thisguy@thisguylabs.com

Discord: this guy

---

Happy Coding! 🧠✨

Making Brainf**k Better, One Function at a Time