BrainCube Language Specification

What is BrainCube?

BrainCube is an esoteric programming language heavily inspired by brainf**k. It was created as a side-project of mine during my freshman year of college, as a way for me to explore programming language design and implementation.

Notable features/quirks of BrainCube include:

• A memory system based in three dimensional space

• Cells that have a capacity determined by their position in memory

• User-defined pointers, which are used for executing all but three commands

• Three or four different control structures, depending on how you count them

BrainCube Standard Specification

First, a note on my use of the word "implementer": When I say implementer in this documentation, I am referring to any implementation of this language, whether it be an interpreter, compiler, or turning machine.

Second, a note on Turing-Completeness: Because this language is a derivative of brainf**k, it is trivial to prove BrainCube is Turing-complete, as it only takes a bit of regex-find-and-replace to translate any conceivable BF program to BrainCube.

Memory System

Programming languages almost always treat memory like a one dimensional array, because that’s more or less what it actually is at the level of assembly language.

In BrainCube, the standard one-dimensional memory space used by most languages is mapped onto a three-dimensional memory space, called the Memory Cube. The three dimensional Memory Cube contains a list of two dimensional sheets. Each sheet contains a list of one dimensional tapes. Each tape contains a list of zero-dimensional cells, which actually hold data.

Each cell can hold a number of bits equal to the index of its parent sheet in the Memory Cube plus one. For example, a cell on sheet 0 would contain 0+1=1 bit, a cell on sheet 1 would contain 1+1=2 bits, a cell on sheet 2 would contain 1+2=3 bits, and so on.

The only time a BrainCube program would directly control memory would be when it calls the ? system command to trigger garbage collection. Otherwise, the implementer will automatically allocate memory for new cells as needed. The implementer will never deallocate/perform a garbage collection without receiving the ? system command. After receiving the ? command, the implementer must deallocate any cell which meets both the following conditions:

1. The cell must have a non-zero value.

2. The cell must not have a role in keeping track of the positions of other non-zero cells.

TL;DR:

• BrainCube has a 3D memory space.

• A cell on sheet N can store N+1 bits.

System Commands

There are three system commands that are used to communicate with the interpreter directly, rather than to manipulate pointers. Because they are not used with pointers, they must appear outside pointer command lists. The system commands are:

• !: Stop program execution before reaching the end of the instructions

• ?: Perform a garbage collection

• #: Debug breakpoint (behavior is implementation-specific)

Example: myptr(XXXXXXX-) (myptr)(myptr(X)) myptr(-)` would cause even the most efficient implementer to allocate at _least_ 264 bits of RAM for data storage, when it only needs to allocate 8 bits of ram. Changing the code to `myptr(XXXXXXX-) (myptr)(myptr(X)) myptr(-) ? would tell the implementer to free up those unneeded bits. Freeing an extra 256 bits of RAM may seem like a waste of time, but when the size of each cell increases with each sheet, RAM can get eaten up pretty quickly.

Pointers

BrainCube, much like its predecessor MindMeld, can support multiple pointers. Unlike MindMeld, however, users of BrainCube may name and use their own pointers.

Pointers are the heart and soul of BrainCube. Without any pointers, all a program could do is exit, or collect garbage it hasn’t produced yet.

Pointer Declaration

Pointers are declared by putting tildes (~) around the name of the pointer.

Pointer names may only contain letters, numbers, and underscores, and must contain at least one letter.

Example: ~myptr~ will declare a new pointer named myptr, initially pointing at sheet 0, tape 0, cell 0, or [0][0][0] for short.

Pointer Commands

A pointer is given commands by naming the pointer, followed by a set of parentheses containing a sequence of pointer commands.

Example: myptr(XX++++>++) moves myptr to [2][0][0], sets that cell’s value to 4, moves myptr to [2][0][1], then sets that value to 2.

MOVEMENT COMMANDS
>	Move the pointer to the right along the tape to the next cell.
<	Move the pointer to the left along the tape to the previous cell.
^	Move the pointer up the sheet to the next tape.
v	Move the pointer down the sheet to the previous tape.
X	Move the pointer forward through the Memory Cube to the next sheet.
O	Move the pointer backward through the Memory Cube to the previous sheet.
DATA MODIFICATION COMMANDS
+	Increase the pointer’s target cell by one, wrapping to zero if need be.
-	Decrease the pointer’s target cell by one, wrapping to the cell’s max value if need be.
OUTPUT COMMANDS
.	Output the value of the target cell as an ASCII character, without a newline.
'	Output the value of the target cell in binary, followed by a newline.
:	Output the value of the target cell as a base10 number, followed by a newline.
INPUT COMMANDS
,	Set the value of the target cell to an ASCII character entered in the console, no followed by a newline.
"	Set the value of the target cell to a binary number entered in the console, followed by a newline.
;	Set the value of the target cell to a base10 number entered in the console, followed by a newline.

Pointer Scope

A pointer declared outside the body of a control flow structure is globally available to all code following the declaration.

A pointer declared inside the body of a control flow structure is available to all code that comes between the declaration and the end of the control flow structure.

Control Flow Structures

Control flow structures have two components, called the head and body.

• The head is the pair of parentheses containing the name of a pointer, and the contained pointer name. It is responsible for controlling the execution of the body’s contents.

• The body is the pair of brackets, and the code contained within said brackets. The type of body brackets determines the type of control flow structure.

If statements

• Format: (head){body}

• Example: (myptr){myptr(-)} will decrement the value of myptr’s target cell if myptr’s target cell is not equal to zero.

While loops

• Format: (head)[body]

• Example: (myptr)[myptr(-)] will decrement the value of myptr’s target cell while myptr’s target cell is not equal to zero.

Repeat Loops

• Format: (head)(body) or (number)(body)

• Examples:

  • (ptr_a)(ptr_b(+)) will increment the value of ptr_b’s target cell n times, where n is the value of ptr_a’s target cell before first entering the repeat loop.

  • (10)(myptr(+)) will increment the value of myptr’s target cell 10 times.

Comments

All comments must start with /* and end with */. Comments do not nest.