Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/neorandom/brainduck-projects
Brainfuck interpreters and compilers. Currently versions are written in Python, C++ and Rust.
https://github.com/neorandom/brainduck-projects
brainfuck brainfuck-interpreter esolang esoteric-interpreter esoteric-language esoteric-programming-language python python3
Last synced: about 2 months ago
JSON representation
Brainfuck interpreters and compilers. Currently versions are written in Python, C++ and Rust.
- Host: GitHub
- URL: https://github.com/neorandom/brainduck-projects
- Owner: neoRandom
- License: mit
- Created: 2023-12-28T03:45:05.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-10-21T03:04:49.000Z (3 months ago)
- Last Synced: 2024-10-29T00:25:56.723Z (2 months ago)
- Topics: brainfuck, brainfuck-interpreter, esolang, esoteric-interpreter, esoteric-language, esoteric-programming-language, python, python3
- Language: Brainfuck
- Homepage:
- Size: 126 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Brainduck Projects
> “Sometimes the questions are complicated, and the answers are simple.” -Dr. Seuss
### **This README is not updated to the latest modifications**
## Description
This project is based on the esoteric Brainfuck language, known for being one of the most difficult to understand and
use, and that's why I made this interpreter in a dynamic and high-level language, Python.
## How to use
### Running in the IDE
In the directories of this project there is the test folder, which contains 4 tests, and the ```run.py``` file. The files in the
test folder work with an external Brainfuck file, while the run file can also work by creating a "shell", like in Python.
After executing the run file in shell mode, the user can type the code and separate it into lines, and as long as the
user does not type an empty line, the program will continue to recive the user input.
To disable the shell and run an external file, you need to change the value of the ```code_path``` variable to the path of
your file, and then your external Brainfuck code will run perfectly.
### Running in the command line interface (CLI)
Alternatively, you can use it through the CLI, which is very simple. The interpreter has 2 call parameters, one being an
option and the other an argument.
```
python brainduck.py --debug [file path]
```
> [file path] is optional
The option causes the code in Brainfuck to run in debug mode (which will be explained later), and the argument, as the
name suggests, is the path to the Brainfuck file.
The argument is optional, and if it is not included, the interpreter will be executed in "shell" mode.
## How the interpreter works
### The BrainDuckInterpreter class
The interpreter is a class that works using the original Brainfuck syntax and rules. The remaining Python files take the
Brainfuck file, read it, separate the text into a list of characters, and filter out those that are not Brainfuck commands.
After that, the command list is sent to an object of the ```BrainDuckInterpreter``` class as a parameter of the run function,
and this creates the memory spaces, defined when creating the object, and other necessary variables.
```
The list of Brainfuck commands:
+ - Increase the value in the cell by 1
- - Decrease the value in the cell by 1
> - Move the memory pointer to the right
< - Move the memory pointer to the left
[ - Start a conditional loop (oversimplified)
] - End a conditional loop (oversimplified)
, - Get the user input and store in the curent memory cell
. - Print the current memory cell value in ASCII table
```
### How the debug mode works
With debug mode activated, each instruction is shown in the CLI the command used, the current cell and the value of the
current cell. Furthermore, when the show cell value command is used, the value is shown as a number, instead of the ASCII (American Standart Code for Information Interchange) character.
### How the compile mode works
Command
```
python brainduck.py --compile [file path]
```
> [file path] is required
### Creating an object from BrainDuckInterpreter
The ```BrainDuckInterpreter``` ```__init__()``` method takes 2 arguments, one is ```memory_bits``` and the other is ```cell_bits```.
As the name suggest, the first defines how many bits the memory will have, consequently defining how many cells there
will be (e.g.: If ```memory_bits``` has the value of 15, there will be 32.768 cells).
The ```cell_bits``` defines how many bits will have each cell (e.g.: If ```cell_bits``` has the value of 8, the maximum
value of the cells will be 255).
### Dependencies
The ```BrainDuckInterpreter``` class is independent of the rest of the project, and can be used in other projects just by
reusing the file, its only dependencies being the command prompt, if a new project wants to use a custom interface it
will have to change the interpreter code a little.
## C++ Version
To compile the C++ version, simply run the make.bat file at the command prompt.
```
C:\brainduck-interpreter\cpp_ver>make
```
And then you can run the code with the parameter being the .bf file you want to run.
```
C:\brainduck-interpreter\cpp_ver>brainfuck test_codes/mandelbrot.bf
```
The code uses stack/compile allocated memory to read the brainfuck and execute it, so there is a limit of 65,536 (or 2 to the power of 16) characters. This version **does not** contain the debug option, other than that it executes the code in a similar way.
## ASCII Table
| Decimal | Hex | Octal | Binary | Character | Description |
|---------|-------|-------|--------------|-----------|--------------------------------|
| 0 | 00 | 000 | 00000000 | NUL | Null character |
| 1 | 01 | 001 | 00000001 | SOH | Start of Heading |
| 2 | 02 | 002 | 00000010 | STX | Start of Text |
| 3 | 03 | 003 | 00000011 | ETX | End of Text |
| 4 | 04 | 004 | 00000100 | EOT | End of Transmission |
| 5 | 05 | 005 | 00000101 | ENQ | Enquiry |
| 6 | 06 | 006 | 00000110 | ACK | Acknowledge |
| 7 | 07 | 007 | 00000111 | BEL | Bell |
| 8 | 08 | 010 | 00001000 | BS | Backspace |
| 9 | 09 | 011 | 00001001 | TAB | Horizontal Tab |
| 10 | 0A | 012 | 00001010 | LF | Line Feed |
| 11 | 0B | 013 | 00001011 | VT | Vertical Tab |
| 12 | 0C | 014 | 00001100 | FF | Form Feed |
| 13 | 0D | 015 | 00001101 | CR | Carriage Return |
| 14 | 0E | 016 | 00001110 | SO | Shift Out |
| 15 | 0F | 017 | 00001111 | SI | Shift In |
| 16 | 10 | 020 | 00010000 | DLE | Data Link Escape |
| 17 | 11 | 021 | 00010001 | DC1 | Device Control 1 (XON) |
| 18 | 12 | 022 | 00010010 | DC2 | Device Control 2 |
| 19 | 13 | 023 | 00010011 | DC3 | Device Control 3 (XOFF) |
| 20 | 14 | 024 | 00010100 | DC4 | Device Control 4 |
| 21 | 15 | 025 | 00010101 | NAK | Negative Acknowledge |
| 22 | 16 | 026 | 00010110 | SYN | Synchronous Idle |
| 23 | 17 | 027 | 00010111 | ETB | End of Transmit Block |
| 24 | 18 | 030 | 00011000 | CAN | Cancel |
| 25 | 19 | 031 | 00011001 | EM | End of Medium |
| 26 | 1A | 032 | 00011010 | SUB | Substitute |
| 27 | 1B | 033 | 00011011 | ESC | Escape |
| 28 | 1C | 034 | 00011100 | FS | File Separator |
| 29 | 1D | 035 | 00011101 | GS | Group Separator |
| 30 | 1E | 036 | 00011110 | RS | Record Separator |
| 31 | 1F | 037 | 00011111 | US | Unit Separator |
| 32 | 20 | 040 | 00100000 | (space) | Space |
| 33 | 21 | 041 | 00100001 | ! | Exclamation mark |
| 34 | 22 | 042 | 00100010 | " | Double quote |
| 35 | 23 | 043 | 00100011 | # | Number sign |
| 36 | 24 | 044 | 00100100 | $ | Dollar sign |
| 37 | 25 | 045 | 00100101 | % | Percent sign |
| 38 | 26 | 046 | 00100110 | & | Ampersand |
| 39 | 27 | 047 | 00100111 | ' | Single quote |
| 40 | 28 | 050 | 00101000 | ( | Left parenthesis |
| 41 | 29 | 051 | 00101001 | ) | Right parenthesis |
| 42 | 2A | 052 | 00101010 | * | Asterisk |
| 43 | 2B | 053 | 00101011 | + | Plus |
| 44 | 2C | 054 | 00101100 | , | Comma |
| 45 | 2D | 055 | 00101101 | - | Hyphen-minus |
| 46 | 2E | 056 | 00101110 | . | Period |
| 47 | 2F | 057 | 00101111 | / | Slash |
| 48 | 30 | 060 | 00110000 | 0 | Digit 0 |
| 49 | 31 | 061 | 00110001 | 1 | Digit 1 |
| 50 | 32 | 062 | 00110010 | 2 | Digit 2 |
| 51 | 33 | 063 | 00110011 | 3 | Digit 3 |
| 52 | 34 | 064 | 00110100 | 4 | Digit 4 |
| 53 | 35 | 065 | 00110101 | 5 | Digit 5 |
| 54 | 36 | 066 | 00110110 | 6 | Digit 6 |
| 55 | 37 | 067 | 00110111 | 7 | Digit 7 |
| 56 | 38 | 070 | 00111000 | 8 | Digit 8 |
| 57 | 39 | 071 | 00111001 | 9 | Digit 9 |
| 58 | 3A | 072 | 00111010 | : | Colon |
| 59 | 3B | 073 | 00111011 | ; | Semicolon |
| 60 | 3C | 074 | 00111100 | < | Less-than sign |
| 61 | 3D | 075 | 00111101 | = | Equals sign |
| 62 | 3E | 076 | 00111110 | > | Greater-than sign |
| 63 | 3F | 077 | 00111111 | ? | Question mark |
| 64 | 40 | 100 | 01000000 | @ | At sign |
| 65 | 41 | 101 | 01000001 | A | Uppercase A |
| 66 | 42 | 102 | 01000010 | B | Uppercase B |
| 67 | 43 | 103 | 01000011 | C | Uppercase C |
| 68 | 44 | 104 | 01000100 | D | Uppercase D |
| 69 | 45 | 105 | 01000101 | E | Uppercase E |
| 70 | 46 | 106 | 01000110 | F | Uppercase F |
| 71 | 47 | 107 | 01000111 | G | Uppercase G |
| 72 | 48 | 110 | 01001000 | H | Uppercase H |
| 73 | 49 | 111 | 01001001 | I | Uppercase I |
| 74 | 4A | 112 | 01001010 | J | Uppercase J |
| 75 | 4B | 113 | 01001011 | K | Uppercase K |
| 76 | 4C | 114 | 01001100 | L | Uppercase L |
| 77 | 4D | 115 | 01001101 | M | Uppercase M |
| 78 | 4E | 116 | 01001110 | N | Uppercase N |
| 79 | 4F | 117 | 01001111 | O | Uppercase O |
| 80 | 50 | 120 | 01010000 | P | Uppercase P |
| 81 | 51 | 121 | 01010001 | Q | Uppercase Q |
| 82 | 52 | 122 | 01010010 | R | Uppercase R |
| 83 | 53 | 123 | 01010011 | S | Uppercase S |
| 84 | 54 | 124 | 01010100 | T | Uppercase T |
| 85 | 55 | 125 | 01010101 | U | Uppercase U |
| 86 | 56 | 126 | 01010110 | V | Uppercase V |
| 87 | 57 | 127 | 01010111 | W | Uppercase W |
| 88 | 58 | 130 | 01011000 | X | Uppercase X |
| 89 | 59 | 131 | 01011001 | Y | Uppercase Y |
| 90 | 5A | 132 | 01011010 | Z | Uppercase Z |
| 91 | 5B | 133 | 01011011 | [ | Left square bracket |
| 92 | 5C | 134 | 01011100 | \ | Backslash |
| 93 | 5D | 135 | 01011101 | ] | Right square bracket |
| 94 | 5E | 136 | 01011110 | ^ | Caret |
| 95 | 5F | 137 | 01011111 | _ | Underscore |
| 96 | 60 | 140 | 01100000 | ` | Grave accent |
| 97 | 61 | 141 | 01100001 | a | Lowercase a |
| 98 | 62 | 142 | 01100010 | b | Lowercase b |
| 99 | 63 | 143 | 01100011 | c | Lowercase c |
| 100 | 64 | 144 | 01100100 | d | Lowercase d |
| 101 | 65 | 145 | 01100101 | e | Lowercase e |
| 102 | 66 | 146 | 01100110 | f | Lowercase f |
| 103 | 67 | 147 | 01100111 | g | Lowercase g |
| 104 | 68 | 150 | 01101000 | h | Lowercase h |
| 105 | 69 | 151 | 01101001 | i | Lowercase i |
| 106 | 6A | 152 | 01101010 | j | Lowercase j |
| 107 | 6B | 153 | 01101011 | k | Lowercase k |
| 108 | 6C | 154 | 01101100 | l | Lowercase l |
| 109 | 6D | 155 | 01101101 | m | Lowercase m |
| 110 | 6E | 156 | 01101110 | n | Lowercase n |
| 111 | 6F | 157 | 01101111 | o | Lowercase o |
| 112 | 70 | 160 | 01110000 | p | Lowercase p |
| 113 | 71 | 161 | 01110001 | q | Lowercase q |
| 114 | 72 | 162 | 01110010 | r | Lowercase r |
| 115 | 73 | 163 | 01110011 | s | Lowercase s |
| 116 | 74 | 164 | 01110100 | t | Lowercase t |
| 117 | 75 | 165 | 01110101 | u | Lowercase u |
| 118 | 76 | 166 | 01110110 | v | Lowercase v |
| 119 | 77 | 167 | 01110111 | w | Lowercase w |
| 120 | 78 | 170 | 01111000 | x | Lowercase x |
| 121 | 79 | 171 | 01111001 | y | Lowercase y |
| 122 | 7A | 172 | 01111010 | z | Lowercase z |
| 123 | 7B | 173 | 01111011 | { | Left curly bracket |
| 124 | 7C | 174 | 01111100 | \| | Vertical bar |
| 125 | 7D | 175 | 01111101 | } | Right curly bracket |
| 126 | 7E | 176 | 01111110 | ~ | Tilde |
| 127 | 7F | 177 | 01111111 | DEL | Delete |
## License
Licensed under the MIT license. See [LICENSE](LICENSE).