view release on metacpan or  search on metacpan

lib/Language/Befunge/doc/bf98-specs.html  view on Meta::CPAN

<p>The co-ordinate mapping used for both Befunge-93 and Funge-98
reflects the "Computer Storage" co-ordinate system used in screen
graphics and spreadsheets; a larger <i>y</i> coordinate means
further down the page.  Compared to a standard mathematical
representation of the usual Cartesian co-ordinate system,
it is upside-down.

<p><table><tr><td><pre>
      Befunge-93                32-bit Befunge-98
      ==========                =================
   0      <i>x</i>     79                      |-2,147,483,648
  0+-------------+                      |
   |                                    |    <i>x</i>
   |                               -----+-----
  <i>y</i>|                  -2,147,483,648    |    2,147,483,647
   |                                    |
   |                                   <i>y</i>|2,147,483,647
 24+
</pre></td></tr></table>

<hr><a name="Stack_Stack"><h3>Stack Stack</h3>

<p>The Funge stack stack is a LIFO stack of typical LIFO stacks
of cells.  In Befunge-93, only two operations
are possible on only one stack (referred to as <i>the stack</i>):
to <i>push</i> a cell onto the top of
the stack, and to <i>pop</i> a cell off the top of the stack.

<p>In the case of Funge-98, however, <i>the stack</i> refers
to the topmost stack on the stack stack.  The push and pop operations
are possible on the stack stack as well, but they push and pop entire
stacks.

<p>There is also a Funge-98 instruction to rid the stack
(that is, the topmost stack of the stack stack) of cells,
completely emptying it.

<p>If a program attempts to pop a cell off the stack when it is empty, no
error occurs; the program acts as if it popped a 0.

<p>In this document, short stacks are generally notated
left to right to mean <b>bottom to top</b>.  The <b>leftmost</b>
values listed in the documentation are the
<b>bottommost</b> and the <b>first</b> to be pushed onto the stack.
Long stacks
are notated top to bottom, to mean precisely that, <b>top to bottom.</b>.

<hr><a name="Format"><h3>Funge Source File Format</h3>

<p>A Befunge-93 source (program) file name, by common convention, ends in
the extension <tt>.bf</tt>.  There is no enforced convention for
what any given Funge-98 source file name ends in (e.g. you could
easily write a C-Befunge polyglot whose file name ends in <tt>.c</tt>), but 
<tt>.b98</tt> is a good choice for Befunge-98 sources
- "standard" example programs use this suffix.

<p>Befunge-93 source files are plain text files containing only printable
ASCII characters and the end-of-line controls described below.

<p>Funge-98 source files are made up of Funge characters.  The
Funge-98 character set overlays the ASCII subset used by Befunge-93
and may have characters greater than 127 present in it (and greater
than 255 on systems where characters are stored in multiple bytes;
but no greater than 2,147,483,647.)  The Funge character set is 'display-independent.'
That is to say, character #417 may look like a squiggle on system
Foo and a happy face on system Bar, but the meaning is always the
same to Funge, 'character #417', regardless of what it looks like.

<p>In other words, what Funge characters look like on a particular computer or
OS depends entirely on that computer or OS.  However, when
characters are not generally considered to be printable, they can
have special meaning to Funge-98:

<ul>
<li>0..31    : "ASCII controls" (only 10 is currently defined to mean EOL)
<li>32..126  : "ASCII printable characters" (all are input/output and fixed-width)
<li>127      : "delete control" (undefined)
<li>128..2bil: "extended printable characters" (machine and font specific)
</ul>

<p>In Befunge-93, each line ends with the current operating system's
"end of line" character, which may be a line feed (10) (Linux),
carriage return (13) (MacOS), or carriage return-line feed (13, 10)
(MS-DOS).

<p>In Funge-98, however, <i>any</i> of the following sequences
should, ideally, be recognized by the interpreter as an end-of-line marker,
no matter <i>what</i> operating system it's running on:
<ul>
<li>Line Feed (10)
<li>Carriage Return (13)
<li>Carriage Return, Line Feed (13, 10)
</ul>

<p>If an interpreter cannot support all three varieties of end-of-line marker,
it should be clearly noted in that interpreter's documentation.

<p>End-of-line markers do <b>not</b> appear in Funge-Space once the
program is loaded.

<p>In Befunge-93, each line can contain up to 80 significant characters
before the "End of Line" marker.  There can be up to 25 such lines in
the source file. There are no such restrictions on Befunge-98 and the
user can reasonably expect to be able to have as many lines of as many
characters as they want, for non-contrived cases.

<p>Before load, every cell in Funge-Space contains a space (32) character.
These default contents are written over by characters in the program
source when it is loaded.  However, spaces in the program source
do not overwrite anything in Funge-Space; in essence the space
character is transparent in source files.  This becomes important when
the <code>i</code> "Input File" instruction is used to include overlapping files.

<p>The source file begins at
the <i>origin</i> of Funge-Space.  Subsequent columns of characters
increment the <i>x</i> coordinate, and subsequent lines increment
the <i>y</i> coordinate (if one is present) and reset the <i>x</i>
coordinate to zero.  Subsequent lines in Unefunge are simply appended
to the first, and the end of the source file indicates the end
of the (single) line.  End-of-line markers are never copied
into Funge-Space.

lib/Language/Befunge/doc/bf98-specs.html  view on Meta::CPAN

toggles a special mode of the Funge
interpreter called <i>stringmode</i>.  In stringmode, every cell 
encountered by the IP (except <code>"</code> and in Funge-98, space)
is not interpreted as an instruction, but rather as a Funge
character, and is pushed onto the stack.  A subsequent <code>"</code>
toggles stringmode once more, turning it off.

<p>In Funge-98 stringmode, spaces are treated "SGML-style";
that is, when any contiguous series of spaces is processed,
it only takes one tick and pushes one space onto the stack.  This
introduces a small backward-incompatibility with
Befunge-93; programs that have multiple spaces and/or wrap while
in stringmode will have to be changed to work the same under
Funge-98.

<pre>
Befunge-93		Befunge-98

"hello world"           "hello world"
"hello   world"         "hello "::"world"</pre>

<p>There is also a <code>'</code> "Fetch Character"
instruction in Funge-98.  This pushes the Funge character value
of the next encountered cell (position + delta) onto the stack,
then adds the delta to the position (like <code>#</code>), skipping
over the character (in no ticks).  For example, the
following two snippets perform the same function, printing a Q:

<p><code>"Q",</code>

<p><code>'Q,</code>

<p><code>s</code> "Store Character" is the mirror image of the
<code>'</code> instruction: this instead pops a value off
the stack and writes it into (position + delta).

<p>Some instructions expect a Funge string on the stack as one of
their arguments. The standard format for these strings is called
<i>0"gnirts"</i> - that is, a null-terminated string with the
start of the string at the top of the stack and the null
termination at the bottom.

<hr><a name="Stack_Manipulation"><h3>Stack Manipulation</h3>

<p>The <code>$</code> "Pop" instruction pops a cell off the stack and
discards it.

<p>The <code>:</code> "Duplicate" instruction pops a cell off the stack, then pushes it
back onto the stack twice, duplicating it.

<p>The <code>\</code> "Swap" instruction pops two cells off the stack, then pushes
the first cell back on, then the second cell, in effect swapping the
top two cells on the stack.

<p>The <code>n</code> "Clear Stack" instruction (not available in Befunge-93)
completely wipes the stack (popping and discarding elements
until it is empty.)

<hr><a name="Stack_Stack_Manipulation"><h3>Stack Stack Manipulation</h3>

<p>The stack stack transparently overlays
the stack - that is to say, the top stack of
Funge-98's stack stack is treated the same as
Befunge-93's sole stack.  The Funge programmer
will never notice the difference unless they
use the <code>{</code>, <code>}</code>, or <code>u</code>
instructions of Funge-98.

<p>When working with different stacks on the stack
stack, though, it's useful to give two of them
names: the <i>top of stack stack</i> or TOSS,
which indicates the topmost stack on
the stack stack, which works to emulate the
sole stack of Befunge-93;
and the <i>second on stack stack</i> or
SOSS, which is the stack directly under
the TOSS.

<p>The <code>{</code> "Begin Block" instruction pops a cell 
it calls <i>n</i>, then pushes a new stack on the
top of the stack stack, 
transfers <i>n</i>
elements from the SOSS to the TOSS,
then pushes the storage offset
as a vector onto the SOSS,
then sets the new storage offset to the location to be
executed next by the IP (storage offset &lt;- position + delta).
It copies these elements as a block, so order is preserved.

<p>If the SOSS contains <i>k</i> elements, where <i>k</i> is less than <i>n</i>, the
<i>k</i> elements are transferred as the top <i>k</i> elements and the remaining
bottom (<i>n-k</i>) elements are filled in with zero-value cells.

<p>If <i>n</i> is zero, no elements are transferred.

<p>If <i>n</i> is negative, |<i>n</i>| zeroes are pushed onto the SOSS.

<p>The corresponding <code>}</code> "End Block" instruction pops a cell off
the stack that it calls <i>n</i>, then pops a vector off the SOSS which
it assigns to the storage offset, then transfers <i>n</i> elements (as a block)
from the TOSS to the SOSS, then pops the top stack off the stack stack.

<p>The transfer of elements for <code>}</code> "End Block" is in all respects
similar to the transfer of elements for <code>{</code> "Begin Block", except
for the direction in which elements are transferred.  "Transfer" is used
here in the sense of "move," not "copy": the original cells are removed.

<p>If <i>n</i> is zero, no elements are transferred.

<p>If <i>n</i> is negative, |<i>n</i>| cells are popped off of the (original) SOSS.

<p><code>{</code> makes the current TOSS the new SOSS.
<code>}</code> makes the current SOSS the new TOSS.

<p><code>{</code> may act like <code>r</code> if no more memory is available for another stack.
<code>}</code> acts like <code>r</code> if a stack-stack underflow would otherwise occur (i.e. when there is only one stack on the stack-stack.)

<p>The practical use of these instructions is to "insulate"
and "localize" procedures or other blocks of Funge code.

<p>The <code>u</code> "Stack under Stack" instruction pops a