BrainFu** Interpreter and Debugger

BrainFu Documentation

Contents

• Emulator Specification
• Emulator Features
• ANSI Terminal with UTF-8
• UTF-8 Output Decoder
• DOS Console
• DOS Console with UTF-8
• Standard Input Box and Console Input
• Standard Output Box
• Language Converter and Language Auto-Detector
• Additional Directives
• Notes

Emulator Specification

• supports both the Ook! language and the Brainfu** language
• 4 MiB cell array
• each cell is a byte with values from 0 to 255
• byte values use wrap-around (modulo arithmetic)
• memory location pointer wrap-around is disallowed (i.e. runtime error)

Emulator Features

• counting executed instructions, with precision of a single instruction
• WebAssembly JIT interpreter with asynchronous execution
• outputs to ANSI terminal or to DOS console
• optional support for UTF-8
• EOF settings
• debugger with two break conditionals
• debugger with memory watch
• includes a language converter and auto-detector

ANSI Terminal with UTF-8

• special character sequences VT100 / VT220 compatible, except when they are not
• 80-column output
• also supports 8-bit ANSI colors
• also supports 24-bit ANSI colors
• current emulation is by Xterm.js 5.4.0; it is imperfect
• Line Feed (U+000A) moves to the start of a new line
• disallowed output code points (cause a runtime error):

               0     NUL     Null Character
               4     EOT     End of Transmission
               5     ENQ     Enquiry
              14     SO      Shift Out
              15     SI      Shift In
              16     DLE     Data Link Escape
              

• color table:

           code   name            normal                bright
          -------------------------------------------------------------
              0   black       (  0,   0,   0)       (128, 128, 128)
              1   red         (205,  40,  40)       (255,  85,  85)
              2   green       (40 , 188,  40)       (  0, 255,   0)
              3   yellow      (188, 188,  40)       (255, 255,   0)
              4   blue        (40 ,  85, 255)       ( 85, 137, 255)
              5   magenta     (192,  40, 192)       (255,   0, 255)
              6   cyan        (40,  188, 188)       (  0, 255, 255)
              7   white       (205, 205, 205)       (255, 255, 255)
              8   normal      (205, 205, 205)       (205, 205, 205)
                  background  ( 20,  20,  20)       ( 20,  20,  20)
              

UTF-8 Output Decoder

• invalid UTF-8 byte sequences result in a runtime error
• only a limited set of code points is supported (due to availability of glyphs in the font)
• outputting an unsupported code point results in a runtime error
• more than 1270 code points are supported; output font is Source Code Pro Medium

DOS Console

• emulates behavior of 80-column DOS console
• uses code page 437 character set, a.k.a. CP437, a.k.a OEM-US
• most output bytes get displayed as a single character
• useful for debugging due to simplicity
• Line Feed (10) moves to the start of a new line
• when the caret moves past column 80, a newline is immediately automatically inserted, which is almost, but not quite, entirely unlike the ANSI terminal behavior
• special characters:

     value  name   width     description
  ----------------------------------------------------------------------------------------------
        0     NUL     1     Null Character: displayed as an empty circle
        7     BEL     0     nothing (should produce a sound, but it doesn't)
        8     BS      -     Backspace: moves the caret one position to the left
        9     HT     1-8    Horizontal Tab: moves the caret to a multiple of 8
       10     LF      -     Line Feed: moves the caret to the beginning of the next row
       13     CR      -     Carriage Return: moves the caret to the beginning of the current row
      127     DEL     1     displayed as an empty square
      255      -      1     displayed as a symbol superscript 3
              

• character set CP437 (32 characters per row):

             ○☺☻♥♦♣♠    ♂♀ ♫☼►◄↕‼¶§▬↨↑↓→←∟↔▲▼
              !"#$%&'()*+,-./0123456789:;<=>?
             @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
             `abcdefghijklmnopqrstuvwxyz{|}~□
             ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜ¢£¥₧ƒ
             áíóúñѪº¿⌐¬½¼¡«»░▒▓│┤╡╢╖╕╣║╗╝╜╛┐
             └┴┬├─┼╞╟╚╔╩╦╠═╬╧╨╤╥╙╘╒╓╫╪┘┌█▄▌▐▀
             αßΓπΣσµτΦΘΩδ∞φε∩≡±≥≤⌠⌡÷≈°∙·√ⁿ²■³
              

DOS Console with UTF-8

• same as DOS Console (see above), but supports UTF-8
• useful for debugging UTF-8 output

Standard Input Box and Console Input

• input is always converted to UTF-8
• all code points are allowed
• Standard Input Box only: EOF at end, behavior selected by input settings

Standard Output Box

• for easy copy-pasting of the output
• always contains Unicode characters (i.e. one character = one code point)
• when UTF-8 output is disabled, all code points are in the range from 0 to 255

Language Converter and Language Auto-Detector

• features the latest almost lossless language-agnostic conversion technology
• engineered to the highest standard of quality: works on my computer

Additional Directives

• %%dbg directive breaks into debugger if the debugger is enabled
• %%dbg directive can optionally be followed by digits, and those digits are retained in the stripped code displayed by the debugger

Notes

• To run Ook! and Brainfu** applications offline, use the OokBF Offline cross-platform package.