BFL (Brainfuck-like Language) Reference

The ewor_brainfuck project includes a higher-level, Brainfuck-like Language (BFL) designed to simplify the development of complex Brainfuck programs, particularly those leveraging BFA Mode for system calls. BFL acts as an abstract syntax tree (AST), allowing developers to write programs using more conventional programming constructs like variables, assignments, arithmetic operations, conditional statements, and loops, which are then compiled down to pure Brainfuck.

The structure of BFL is defined by the BFLNode enum in src/bfl.rs. Each variant represents a distinct element or operation within the BFL language. The BFL Compiler Architecture and Internals page provides details on how the BFLCompiler processes these nodes to generate Brainfuck code.

BFLNode Variants

Here's a breakdown of each BFLNode variant, its purpose, and how it conceptually translates into Brainfuck operations.

---

Assign(String, Box<BFLNode>)

• Purpose: Assigns the result of an expression to a named variable. If the variable doesn't exist, it is declared and allocated a new memory cell.
• Semantics: variable_name = expression
• Brainfuck Translation:
  1. The compiler allocates a unique memory cell for the variable_name.
  2. The expression is evaluated, and its result is placed into the allocated cell for the variable_name. This typically involves clearing the target cell ([-]) and then using + operations to set its value, or using copy/move patterns if the expression is a variable.
• Conceptual BFL Example (Rust Syntax):
  This would assign the value 42 to a variable named x.

---

Variable(String)

• Purpose: Represents a reference to a named variable, used within expressions.
• Semantics: variable_name
• Brainfuck Translation: When a variable is referenced in an expression, its assigned memory cell address is used. Operations like Add or Sub will typically copy the variable's value to a scratch cell before performing arithmetic, to preserve the original variable's value.
• Conceptual BFL Example (Rust Syntax):
  This would represent the value stored at the memory location associated with "my_var".

---

String(String)

• Purpose: Represents a literal string value.
• Semantics: "Hello, World!"
• Brainfuck Translation:
  1. The compiler allocates a contiguous block of memory cells to store the ASCII byte values of the string characters.
  2. Each cell in this block is initialized with the corresponding character's ASCII value using + operations.
  3. A separate variable cell is allocated (if part of an Assign statement) to store the starting memory address (a "pointer") of this string data.
• Conceptual BFL Example (Rust Syntax):
  This would store the bytes for "Hello, BFL!" in memory and return the starting address.

---

Number(i32)

• Purpose: Represents a literal integer value.
• Semantics: 123
• Brainfuck Translation: When evaluated, the target memory cell is cleared ([-]) and then incremented (+) n times to set its value.
• Conceptual BFL Example (Rust Syntax):
  This represents the numeric value 10.

---

Bytes(Vec<u8>)

• Purpose: Represents a literal sequence of raw byte values. This is similar to String but takes a Vec<u8>, useful for binary data like network addresses.
• Semantics: [0x02, 0x00, ...]
• Brainfuck Translation:
  1. The compiler allocates a contiguous block of memory cells for the byte array.
  2. Each cell is initialized with the corresponding byte value.
  3. Similar to String, a pointer to the start of this byte data is stored in a designated variable cell.
• Conceptual BFL Example (Rust Syntax):
  This would store the raw byte sequence in memory and return its starting address.

---

Add(Box<BFLNode>, Box<BFLNode>)

• Purpose: Performs addition of two expressions.
• Semantics: expression_a + expression_b
• Brainfuck Translation:
  1. The left-hand side (lhs) expression is evaluated into the target cell (e.g., the cell assigned to a variable).
  2. The right-hand side (rhs) expression is evaluated into a temporary "scratch" cell (e.g., SCRATCH_1 in src/bfl.rs).
  3. A Brainfuck loop ([ ]) is used to destructively move the value from the scratch cell to the target cell, effectively adding them: [<+>-] (assuming scratch is to the right of target, this pattern moves value from current to left, then decrements current).
• Conceptual BFL Example (Rust Syntax):
  This would add 1 to the value of the variable count.

---

Sub(Box<BFLNode>, Box<BFLNode>)

• Purpose: Performs subtraction of two expressions.
• Semantics: expression_a - expression_b
• Brainfuck Translation:
  1. The left-hand side (lhs) expression is evaluated into the target cell.
  2. The right-hand side (rhs) expression is evaluated into a temporary "scratch" cell.
  3. A Brainfuck loop ([ ]) is used to destructively move the value from the scratch cell, decrementing the target cell for each unit moved: [<-+>] (assuming scratch is to the right of target). The operation implicitly clamps at 0 for unsigned 8-bit cells.
• Conceptual BFL Example (Rust Syntax):
  This would subtract 1 from the value of the variable counter.

---

If(Box<BFLNode>, Vec<BFLNode>)

• Purpose: Executes a block of statements only if a given condition evaluates to a non-zero value.
• Semantics: if (condition) { statements }
• Brainfuck Translation:
  1. The condition expression is evaluated into a temporary "condition" cell (e.g., SCRATCH_2 in src/bfl.rs).
  2. A Brainfuck loop [ ... ] is wrapped around the body statements. This loop will execute only if the condition cell is non-zero.
  3. Crucially, inside the loop, after the body statements, the condition cell is cleared ([-]). This ensures the if block executes only once, as Brainfuck loops repeat until the current cell is zero.
• Conceptual BFL Example (Rust Syntax):
  If flag is non-zero, result will be set to 1.

---

While(Box<BFLNode>, Vec<BFLNode>)

• Purpose: Repeatedly executes a block of statements as long as a given condition evaluates to a non-zero value.
• Semantics: while (condition) { statements }
• Brainfuck Translation:
  1. The condition expression is initially evaluated into a temporary "condition" cell.
  2. A Brainfuck loop [ ... ] is wrapped around the body statements.
  3. Inside the loop, after executing the body statements, the condition expression is re-evaluated and its value placed back into the condition cell. This allows the loop to check the updated condition before the next iteration.
• Conceptual BFL Example (Rust Syntax):
  This would decrement i until it reaches zero.

---

Syscall(Box<BFLNode>, Vec<BFLNode>)

• Purpose: Executes a system call, allowing BFL programs to interact with the operating system for tasks like I/O, networking, and process management.
• Semantics: syscall(syscall_number, arg1, arg2, ...)
• Brainfuck Translation: This is where BFL directly leverages BFA Mode.
  1. The syscall_number expression is evaluated and its result placed into Brainfuck cell 7.
  2. Each argument in args is evaluated and its result placed into Brainfuck cells 1 through 6, respectively.
  3. Finally, a single . (dot) instruction is appended to the Brainfuck output. In BFA Mode, this . instruction triggers the system call defined by cells 1-7.
  4. The return value of the syscall is stored in Brainfuck cell 0, accessible via the special _syscall_result variable.
• Conceptual BFL Example (Rust Syntax):
  This would write 13 bytes from the message variable to standard output. For a complete list of supported syscalls and their conventions, refer to the Brainfuck with Syscall Extensions (BFA Mode) page.

---

Block(Vec<BFLNode>)

• Purpose: Groups a sequence of BFL statements together. This is fundamental for structuring programs, especially within If and While bodies or as the top-level program.
• Semantics: { statement1; statement2; ... }
• Brainfuck Translation: The Brainfuck code generated for each statement within the block is simply concatenated in order.
• Conceptual BFL Example (Rust Syntax):
  This represents a sequence of operations.

---

By providing these structured constructs, BFL significantly simplifies the process of writing complex Brainfuck programs. You can explore Practical Examples like examples/hello_bfl.rs and examples/ping_pong_server.rs to see BFL in action.