README.md (7405 bytes)
1 # Brainfuck from within Common Lisp 2 LispFuck is a simple Brainfuck interpreter written in Common Lisp. It has the best brainfuck debugging capabilities currently in existence, and code can be interpreted or compiled. Users may: view the tape contents or individual cell contents, find the final position of execution in the tape, change the length of the byte tape in the REPL, and more. 3 [](https://raw.githubusercontent.com/equwal/LispFuck/master/pics/repl.png) 4 5 # Brainfuck 6 Brainfuck is an esoteric programming language that works on a theoretical byte tape (the Universal Turing Machine). The commands are: 7 ``` 8 > Move to the next byte on the right. 9 < Move to the next byte on the left. 10 . Print the current byte using ASCII. 11 , Read a character of input into this byte. 12 + Increment this byte's value by one. If the cell value is 255 then set it to 0. 13 - Decrease the value of this cell by one. If the cell value is 0 then set it to 255. 14 [ Start a loop. It will be skipped if the current byte is zero, and if not it will terminate at the 15 following "]" when the cell is finally set to zero. 16 ] Delimit the end of a loop. 17 Any other character is considered a "comment" meaning it does nothing. 18 ``` 19 20 These can be combined into a string such as the following "Hello World!" program: 21 ``` 22 > #f++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++. 23 "Hello World! 24 " 25 ``` 26 # How to install: 27 - Make sure you have a Common Lisp implementation installed. I recommend [Steel Bank Common Lisp](http://www.sbcl.org/). 28 - [ASDF](https://common-lisp.net/project/asdf/) must be installed. Many Lisps come with it, no installation necessary (including [SBCL](http://www.sbcl.org/)). 29 - Install this code into your ASDF *load directory*. The default on linux is usually `~/common-lisp/`: 30 ``` 31 me@linux:~$ mkdir common-lisp 32 me@linux:~$ cd common-lisp 33 me@linux:~/common-lisp$ git clone https://github.com/equwal/LispBrain.git 34 ``` 35 - Run your favourite Common Lisp implementation and load the :brain package: 36 ``` 37 > (asdf:load-system :brain) 38 ``` 39 40 If you are unable to find where the ASDF load directory is, you may choose to load the files thusly: 41 ``` 42 > (load "[filepath]/code/packages.lisp") 43 > (load "[filepath]/code/interpreter.lisp") 44 > (load "[filepath]/code/brain.asd") 45 > (asdf:load-system :brain) 46 ``` 47 48 In Allegro common lisp one must first use `(require :asdf)` before executing any other commands in order to activate the preinstalled ASDF system. 49 # How to Use: 50 If everything runs smoothly you will be ready to Brainfuck. If there are issues then please *let it be known*. Now one must choose between the `brain:fuck` and the `#F` notation when using the REPL. The `#F` notation is more concise but does not allow any whitespaces or closing parenthesis in the Brainfuck code, while the `brain:fuck` notation allows any character except for an unescaped literal quote `"`, or an unescaped literal backward slash `\` inside of the Brainfuck code. Below they are both shown: 51 ``` 52 Note: This program prints out an ASCII table using a loop. 53 > (brain:fuck ".+[.+] Please escape your \" and \\ characters!") 54 "� 55 56 57 58 59 60 61 !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ 62 ¡¢£¤¥¦§¨©ª«¬®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ" 63 ``` 64 [](https://raw.githubusercontent.com/equwal/LispFuck/master/pics/brain-fuck-notation.png) 65 ``` 66 > #f.+[.+] <This is not inside the Brainfuck code, nor is + or -.>[] 67 "� 68 69 70 71 72 73 74 !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ 75 ¡¢£¤¥¦§¨©ª«¬®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ" 76 ``` 77 [](https://raw.githubusercontent.com/equwal/LispFuck/master/pics/pound-f-notation.png) 78 79 Code can be saved in a file and run at the repl with the `(load "filepath")` command, and compiled with the `(compile-file "filepath")` command. [SBCL](http://www.sbcl.org/) will always compile your code for you. I recommend not compiling code unless speed is truly important; compiling can make the debugging capabilities of Common Lisp implementations less usable. 80 81 # Debugging Brainfuck 82 83 Debugging Brainfuck code can be done using all the normal Common Lisp functions: `step`, `trace`, `time`, etc. The following functions and variables are exported to the user and may be useful for debugging Brainfuck code: 84 ``` 85 brain:fuck ;Used to execute a Brainfuck string directly. 86 brain:*tape-size-default* ;Number of cells in the tape. Default: 30,000. 87 brain:decf-byte ;The - operator function. 88 brain:incf-byte ;The + operator function. 89 brain:read-this-byte ;The , operator function. 90 brain:print-this-byte ;The . operator function. 91 brain:right-shift ;The > operator function. 92 brain:left-shift ;The < operator function. 93 brain:one-off-fuck ;Function called to loop over each character in the code. 94 brain:*separators* ;Characters that terminate #F Brainfuck code. Defaults: #\Space #\) #\Newline. 95 brain:byte-value ;Returns the value of the curren byte at the *pointer* position. 96 brain:*tape* ;Stores the entire tape. 97 brain:*pointer* ;Stores the current position in the byte tape. Useful with byte-value. 98 Default: Exactly in the middle of the tape (15,000). 99 ``` 100 Note that the variables `*tape*` and `*pointer*` are reset upon executing new Brainfuck code. Once the execution is finished their state is frozen in time and ready to be viewed. 101 102 # Examples for Debugging: 103 Suppose you want to make the tape only 10 bytes long (instead of the default 30000) This way you can easily view the tape contents after execution: 104 ``` 105 > (setf brain:*tape-size-default* 10) ;Sets the tape to only elements 0 to 9 106 > #f->+ ;Sets cell to 255, shifts right and sets to 1 107 > brain:*tape* ;Holds the byte tape vector 108 #(0 0 0 0 0 255 1 0 0 0) 109 > brain:*pointer* 110 6 111 > (byte-value) 112 1 113 ``` 114 Suppose you want to find information about the execution of `incf-byte` and `decf-byte`: 115 ``` 116 > (trace brain:incf-byte brain:decf-byte) 117 > (brain:fuck "+-") 118 ;;;; The following text is implementation dependent, and looks exactly like this only on SBCL 119 0: (INCF-BYTE) 120 0: INCF-BYTE returned 1 121 0: (DECF-BYTE) 122 0: DECF-BYTE returned 0 123 "" 124 ``` 125 126 # Brain 127 - A recently deceased human brain being handled. It jiggles like jello: https://www.youtube.com/watch?v=jHxyP-nUhUY 128 129 # Conclusion 130 All of the colorful pictures of code being executed were taken using Emacs and Slime, and edited with GIMP. 131 132 Please sumbit any feedback to me via email. 133 134 This software is licensed under the MIT free software license. 135 ====