
                          Befunge-93 Documentation
     _________________________________________________________________
                                      
    Twisted, Deranged Programming Language in the Tradition of BrainF***
                                 and False
                                      
                               Chris Pressey
                     Original document September, 1993
                           Updated December, 1996
                                      
  The Basics of Befunge-93
  
   Most likely the most unique element of Befunge-93 programming is the
   Program Counter (PC.) In almost all computer programming languages,
   the program counter is continually moving forward through the program,
   occassionally jumping to another spot in the code (but continuing
   forwardthereafter nonetheless.)
   
   The PC in Befunge-93, however, is subject to different rules. It may
   go forward, backward, left or right. A Befunge-93 program is treated
   as an 80x25 torus (a page which wraps around on the edges) of ASCII
   text. Certain commands change the direction of the progress of the PC.
   By default, the PC points to the upper-left corner of the program, and
   is oriented to travel left-to-right.
   
   Each command in Befunge-93 is a single character, as is the largest
   data unit; Befunge-93 programs have a maximum size of 80x25 total
   commands and data bytes. There are no run-time variables and a single
   run-timestack. Befunge-93 programs allow for self-modification. Due to
   the 2-dimensional nature of the PC, they allow for some extremely
   quirky code.
   
  The Stack
  
   Something like Forth and PostScript, Befunge-93 supports a LIFO,
   Reverse Polish Notation (RPN or postfix) stack of signed long
   integers. The act of placing a value on the stack is called pushing,
   and the act of taking a value off the stack is called popping. The
   digits from '0' to '9' are valid Befunge-93 commands which push their
   respective values onto the stack. A double quote '"', when
   encountered, toggles stringmode, and while stringmode is active, all
   character cells will have their ASCII value pushed onto the stack
   until another '"' is located.
   
   There are a few basic calculation commands:
   
     * '+' addition
     * '-' subtraction
     * '/' integer division
     * '*' multiplication
     * '%' modulo
     * '!' logical negation
       
   These are explained in greater detail in the Commands section.
   
   In order to push a number greater than 9 on the stack, calculations
   must be done with numbers less than or equal to 9. In any other
   language this would be a pain. In Befunge-93 it is a joy. For example,
   to push '123' onto the stack, one might push 9, then 9, then multiply
   (leaving 81), then push 7, then 6, then multiply (leaving 81 and 42,)
   then add (leaving 123.) In Befunge, this would look something like :
   
   99*76*+
       
   This is, of course, assuming (correctly) that the PC starts at or
   before the first '9' and is working towards the right.
   
   NB. If the stack is be empty when you pop something off, be warned
   that this will not generate an underflow! It will simply return '0' to
   you. Hope you can live with it!
   
  The Program Counter in Detail
  
   There are 5 commands which directly control the PC direction: '>',
   '<', 'v', '^', and '?'. '>' makes the PC travel to the right; '<' to
   the left;'v' down; '^' up; and '?' in a random direction. So, the
   following example is an infinite loop :
   
   ><
       
   As is :
   
   >v^<
       
   As is :
   
   >v>v >^v^ <
       
   Note that ' ' (space) is a null command which does nothing.
   
   Should the PC encounter the 'edge' of the program, such as if you were
   to try to execute:
   
   <
       
   The PC will 'wrap around' to the other 'edge' of the program. This,
   too, is an infinite loop.
   
  Decision Making
  
   The standard 'if' statement in Befunge is either '_' or '|', depending
   on how you want to branch. Both pop a value off the stack and check to
   see if it is true (non-zero,) and change the direction of the PC
   accordingly.
   
   '_' acts like '<' if it is true, and '>' if it is false.
   '|' acts like '^' if it is true, and 'v' if it is false.
   
   'While' loops can be made by sticking an 'if' in an infinite loop. For
   example,
   
   >_@
       
   (This program fragment pops all of the non-zero values off the stack,
   and the first zero value, then exits ['@' is the exit command.])
   
  Input
  
   The '&' command will get a numeric value from the standard input and
   push it on the stack. '~' will get the next ASCII character from
   standard input and push it on the stack.
   
   eg.
   
   &,
       
   ...prints out "A" if the user types "65 ", and...
   
   ~.
       
   ...prints out "65 " if the user types "A".
   
  Output
  
   The '.' command will pop a value off the stack and output it as an
   integer, followed by a space. (somewhat like Forth.) ',' will pop
   avalue and output as ASCII with no space.
   
   eg.
   
   665+*1-,
       
   ...prints out ASCII 65 ("A".), and...
   
   665+*1-.
       
   ...prints out "65 ".
   
  Special Commands
  
   '#' is the 'bridge' command... it causes the next command which would
   normally be executed to be skipped over, and not executed. For
   example,
   
   >123...@
       
   would output "3 2 1 " but
   
   >123#...@
       
   would output "3 2 " with one of the '.''s being skipped. Judicious use
   of '#' can make for very interesting code!
   
   ':' is the duplicating command. It makes a copy of the top element of
   the stack. This is useful, as demonstrated in the program below.
   
   v.<>:| @
       
   This makes duplicates of each value on the stacked, which is checked,
   and if non-zero, printed.
   
   '$' pops a value off the stack, but does nothing with it. So,
   
   123.$.@
       
   results in "3 1 ".
   
   '\' swaps the top two elements of the stack. So,
   
   123\...@
       
   results in "2 3 1 ".
   
   '`' (back-quote) is the 'greater' command. It compares the top two
   values on the stack, and returns '1' if the first is greater than the
   second.
   
   eg.
   
   65`.
       
   ...outputs "1 " and...
   25`.
       
   ...outputs "0 ".
   
  Appendix A. Command Summary
  
COMMAND         INITIAL STACK (bot->top)RESULT (STACK)
-------         -------------           -----------------
+ (add)         <value1> <value2>       <value1 + value2>
- (subtract)    <value1> <value2>       <value1 - value2>
* (multiply)    <value1> <value2>       <value1 * value2>
/ (divide)      <value1> <value2>       <value1 / value2> (nb. integer)
% (modulo)      <value1> <value2>       <value1 mod value2>
! (not)         <value>                 <0 if value non-zero, 1 otherwise>
` (greater)     <value1> <value2>       <1 if value1 > value2, 0 otherwise>
> (right)                               PC -> right
< (left)                                PC -> left
^ (up)                                  PC -> up
v (down)                                PC -> down
? (random)                              PC -> right? left? up? down? ???
_ (horizontal if) <boolean value>       PC->left if <value>, else PC->right
| (vertical if)   <boolean value>       PC->up if <value>, else PC->down
" (stringmode)                          Toggles 'stringmode'
: (dup)         <value>                 <value> <value>
\ (swap)        <value1> <value2>       <value2> <value1>
$ (pop)         <value>                 pops <value> but does nothing
. (pop)         <value>                 outputs <value> as integer
, (pop)         <value>                 outputs <value> as ASCII
# (bridge)                              'jumps' PC one farther; skips
                                        over next command
g (get)         <x> <y>                 <value at (x,y)>
p (put)         <value> <x> <y>         puts <value> at (x,y)
& (input value)                         <value user entered>
~ (input character)                     <character user entered>
@ (end)                                 ends program

  The People Who Helped Make the Dream Reality
  
   Special thanks to Curtis Coleman, Jason Goga, Kalyna Zazelenchuk,Shawn
   Vincent, Mike Veroukis, Urban Mueller, and Wouter van Oortmerssen.

