Getting Started: Running Brainfuck and BFL

This guide will walk you through setting up, building, and running the ewor_brainfuck project, covering both native Brainfuck (.bf), Brainfuck with Syscall Extensions (.bfa), and the higher-level Brainfuck-like Language (BFL).

Prerequisites

To get started, you'll need:

• Rust and Cargo↗: The project is written in Rust, and Cargo is its build system and package manager.

1. Clone the Repository

First, clone the ewor_brainfuck repository to your local machine:

2. Build the Project

Once inside the project directory, you can build the main executable and all examples using Cargo:

This command will compile the ewor_brainfuck library, the main application (which acts as an interpreter), and all example programs.

3. Execute a Standard Brainfuck (.bf) File

The project includes a utility example, examples/run_bf.rs, specifically designed for running standard Brainfuck .bf files. This utility uses the BF interpreter in its basic mode.

examples/run_bf.rs Utility Code

Usage

1. Build the example:

2. Run with a .bf file: The ewor_brainfuck project doesn't directly include .bf files in the repository. However, the examples/bfa_hello_world_gen.rs example generates a bfa_hello_world.bf file that can be used for testing. First, run the generator:
   This will create bfa_hello_world.bf in your project root. Now you can run it:
   You should see "Hello World!" printed to your console.

4. Execute a Brainfuck with Syscall Extensions (.bfa) File

The main ewor_brainfuck executable (src/main.rs) can interpret Brainfuck code. It automatically switches to BFA Mode if the input file has a .bfa extension. This mode enables direct system calls, crucial for networking applications like the ping-pong server example.

Usage

While the project primarily focuses on generating .bf or .bfa files from BFL, you can create a .bfa file manually or use one generated by BFL examples. For instance, the bfa_hello_world_gen.rs example also creates bfa_hello_world.bf which, despite the .bf extension, contains syscalls and should ideally be run in BFA mode for correct output. The main.rs interpreter will run a .bf file that contains syscalls, but it's recommended to use the .bfa extension for clarity if syscalls are present.

1. Generate bfa_hello_world.bf (if you haven't already):

2. Run with the main interpreter:
   Again, "Hello World!" should be printed. This command runs the main src/main.rs executable, which detects the file and runs it. If the file were bfa_hello_world.bfa, it would explicitly activate Mode::BFA.

For more details on the extended instruction set, refer to the Brainfuck with Syscall Extensions (BFA Mode) page.

5. Compile and Run BFL Code (Written in Rust)

The BFL (Brainfuck-like Language) is a higher-level language defined and compiled within the Rust project itself. This means you don't write .bfl files directly. Instead, you write Rust code that defines a BFL program using an Abstract Syntax Tree (AST) (represented by BFLNodes) and then use the BFLCompiler to translate it into Brainfuck code. This generated Brainfuck code is then executed by the BF interpreter in BFA Mode.

The examples/ directory contains several Rust programs that demonstrate BFL compilation and execution.

Illustrative Examples

examples/hello_bfl.rs

This example defines a "Hello, World!" program using BFL nodes, including a Syscall to write to standard output. It then compiles and runs it.

examples/bfa_hello_world_gen.rs

This example also generates "Hello World!" but demonstrates a more direct way of embedding a string and printing characters using individual syscalls. It also saves the generated Brainfuck code to a file (bfa_hello_world.bf).

Usage

To run any of the BFL examples:

Each of these commands will:

1. Compile the Rust example program.
2. The Rust program will use the BFLCompiler to convert its internal BFLNode representation into Brainfuck code.
3. The Rust program will then instantiate the BF interpreter with the generated Brainfuck code in BFA Mode.
4. Finally, the BF interpreter will execute the Brainfuck code.

This workflow illustrates the full power of the BFL compiler architecture and its interaction with the BFA interpreter, enabling complex programs to be written and executed. For more information on BFL syntax and features, see the BFL (Brainfuck-like Language) Reference.