bfdb(1)

NAME
bfdb - BF interpreter, debugger and compiler

SYNOPSIS
bfdb ( -n )

DESCRIPTION
bfdb is an interactive interpreter, debugger and compiler for the BF language. Once run, it prompts the user for bfdb commands, which it then executes. Available bfdb commands are listed below under COMMANDS.

LANGUAGE
BF runs on a tape-based virtual machine. Each cell of the tape is indexed by an integer (its address), and in addition, contains one integer. Initially, each cell in the tape contains zero. The tape has one head, which can point to any cell on the tape; initially, the head is at address zero. A BF program consists of a sequence of ASCII characters. The eight characters +, -, >, <, [, ], ,, and . are the executable instructions of BF. All other characters have no effect when executed and may be used to comment the BF program. The eight characters are executed as follows:

+   Increment the value in the head's cell by one.

-   Decrement the value in the head's cell by one.

>   Move the head one cell to the right (i.e., increment its address by one.)

<   Move the head one cell to the left (i.e., decrement its address by one.)

The instructions [ and ] are matched in pairs, using the usual conventions for parenthesization. If this cannot be done because the occurrences of [ and ] are not balanced, the BF program is ill-formed.

[   If the head's cell contains zero, jump forward to the instruction following the matching ].

]   Jump backwards to the matching [. (The [...] construct thus serves as a while loop that executes as long as the head's cell is nonzero.)

,   Accept one character of input and place its value in the head's cell.

.   Take the value in the head's cell and write an output character whose value equals this value.

LANGUAGE VARIANTS
bfdb supports a doubly infinite tape; it also supports a tape which is bounded, either at the left, at the right, or both. In addition, the values of tape cells can be constrained to lie between lower and upper bounds. If one of these bounds is reached, bfdb will either abort, limit the head position or cell value at the bound, or wrap the head position or cell value around to the opposite bound. The user may specify which of these is done.

bfdb can read characters either as signed (with values from -128 to 127) or unsigned (with values from 0 to 255); writing characters is always done by taking the low 8 bits of the value's binary representation. bfdb can also optionally read and write decimal numbers instead of characters.

If the BF program attempts to read past end-of-file, the user can choose to have bfdb abort the program, halt it normally, do nothing, or store a specified end-of-file value into the head's tape cell.

OPTIONS

-n  Non-interactive mode: all prompts are suppressed.

COMMANDS

% text
    Lines starting with % have no effect and may be used to comment debugger input.

?   Show a summary of available commands.

break at location
    Set a breakpoint at location. Locations are measured in characters from the start of the program; the start of the program is considered to be at 0.

clear
    Clear tape to all zeroes. Does not move the head.

compile "output-file-name"
    Compile the program into C and write the C code to output-file-name. See NOTES below for remarks on compilation.

delete number
    Delete the numberth breakpoint.

exit
    Leave bfdb.

help
    Same as ?.

load "code-string"
    Load the BF program given by the sequence of characters in code-string. The PC (execution location) is reset to 0, and all breakpoints are deleted.

quit
    Same as exit.

read "filename"
    Read the BF program contained in filename. The PC is reset to 0, and all breakpoints are deleted.

run (at loc) (for num)
    Run the program starting at location loc until it halts, reaches a breakpoint, aborts with an error, or executes num instructions. If at loc is omitted, execution starts at the current PC. If for num is omitted, execution continues until the program halts, reaches a breakpoint, or aborts with an error.

set bound num
    Place the bound bound at num. bound may be left, right, low, or high.

set bound (num) abort
    Cause the bound bound to abort upon being hit and, if num is present, place it at num.

set bound (num) limiting
    Make the bound bound limiting and, if num is present, place it at num.

set bound (num) wrap(around)
    Make the bound bound wraparound and, if num is present, place it at num. A wraparound bound may not be placed opposite to an infinite bound.

set bound infinite
    Make the bound bound infinite (i.e., delete it.) A bound placed opposite to a wraparound bound may not be made infinite.

set default
    Reset the bounds, input method, output method, and EOF processing method to the default, which is: no bounds; take input as unsigned characters; write output as characters; and set the head's tape cell to -1 upon encountering EOF.

set eof abort
    Change EOF processing to abort the program.

set eof halt
    Change EOF processing to halt the program normally.

set eof nop
    Change EOF processing to do nothing.

set eof (value) num
    Change EOF processing to place num in the head's tape cell.

set input decimal
    Change the input method to read in decimal numbers.

set input signed (char)
    Change the input method to read in signed characters.

set input (unsigned) char
    Change the input method to read in unsigned characters.

set input unsigned
    Same as set input unsigned char.

set output char
    Change the output method to write characters.

set output decimal
    Change the output method to write decimal numbers.

set pc num
    Set the PC to num.

set position num
    Set the head's address to num.

set tape address num.
    Set the value in cell address to num.

show
    Show the current PC, head position, breakpoints, bounds, input method, output method, and EOF processing method.

show copying
    Show license info.

show license
    Same as show copying.

show prog (num) (at loc)
    Show num characters of the program around location loc. If at loc is omitted, the characters around the current PC are shown.

show tape (num) (at loc)
    Show num cells of the tape around location loc. If at loc is omitted, the cells around the head are shown.

show warranty
    Inform the user that there is absolutely no warranty.

NOTES
Breakpoints are not renumbered when a breakpoint is deleted.

If a value in a cell becomes invalid because the cell value bounds are changed, then, regardless of the bound processing option, the value is truncated to the relevant bound. This is also done if the value to write upon EOF becomes invalid because the cell value bounds are changed, the user attempts to set a tape cell to an invalid value from the bfdb command line, a character or decimal number whose value is outside the cell value bounds is read in, or the head position becomes invalid because the tape bounds are changed.

The interpreter is faster if each of the four bounds is either infinite or wraparound.

For compilation, all bounds must exist and be wraparound. In addition, the lower and upper cell value bounds must match the minimum and maximum values of one of the following C integral types: unsigned char, int, unsigned, long, or unsigned long. The compiler assumes (1) that the sizes of and values taken by these types on the target architecture are the same as on the architecture on which bfdb was compiled, (2) that these integral types are represented on the target architecture by unsigned binary numbers, in the case of unsigned types, or two's-complement binary numbers, in the case of signed types, (3) that each type is at least 8 bits long (9 bits for the signed types), and (4) that the number of cells in the tape is no bigger than the maximum value representable by size_t on the target architecture.

The interpreter may detect some infinite loops and halt if it encounters them. This is also the case for the code produced by the compiler.

The BF language was invented by Urban Müller.

SEE ALSO
bflen(1)

AUTHOR
David Moews - dmoews@fastmail.fm