| blob | cb2b85f3aca8fbd816b24c032b2914d07d64fea9 |
1 <html>
2 <head>
4 </head>
9 </center>
11 <ul>
13 <ul>
16 </ul>
18 <ul>
23 </ul>
25 <ul>
32 </ul>
34 <ul>
39 </ul>
41 <ul>
47 </ul>
49 <ul>
53 </ul>
55 <ul>
60 </ul>
61 </ul>
67 <p>Funges are programming languages whose programs are
68 typically expressed in a given topological pattern and
69 number of dimensions.
74 an update of the original Befunge-93 language definition.
77 officially sanctioned programming languages
78 (Unefunge, Befunge, and Trefunge) and provides a
79 paradigm for describing any number of imaginary ones
80 with different topologies and any number of dimensions.
82 <p>The most popular Funge by far is Befunge, which
83 is two-dimensional and based on a Cartesian Lahey-Space
84 (or Cartesian Torus, in Befunge-93 only) topology.
85 Other Cartesian Lahey-Space Funges include Unefunge (one-dimensional)
86 and Trefunge (three-dimensional.) Since not all Funge instructions
87 are appropriate in all Funges, comparison to Befunge is often
88 used to clarify points in this document.
92 <p>This is a final document. The information it contains has been formally
93 approved and it is endorsed by its supporters as the 'official'
94 technical specification of the Funge language family.
96 <p>This document is suitable for an
97 audience not already familiar with any Funge of any kind or year.
103 <p>Any given piece of code or data in a Funge
106 <ul>
108 dimensionality, topology and tiling pattern of the Funge,
114 and it's accessed as a last-in, first-out (LIFO) stack of cells.
115 </ul>
119 alike should be treated as signed integers of the same size.
121 <p>What size exactly is left up to the implementer.
123 separate variations on Funge-98.
124 More than 32 bits is just fine. The important thing is that the
125 stack cells have the same memory size as the Funge-Space cells.
132 interpreter, ideally, has an addressing range equal to that
134 uses signed 32-bit integers as each of its coordinate indices.
137 is generally considered to be dynamically allocated
138 by some behind-the-scenes mechanism in the compiler.
141 <p>So, the storage mechanism has be consistently trustworthy about
142 how it provides Funge-Space to the running program.
143 A Funge-98 program should be able to rely on all code and data
144 that it puts in Funge-Space through this mechanism not disappearing.
145 A Funge-98 program should also be able to rely on the memory mechanism
146 acting as if a cell contains blank space (ASCII 32) if it is
147 unallocated, and setting memory to be full of blank space cells upon
149 If the underlying memory mechanism cannot provide this (e.g. no more
150 memory is available to be allocated,) the interpreter should complain
151 with an error and do what it can to recover, (but not necessarily
152 gracefully).
155 reflects the "Computer Storage" co-ordinate system used in screen
157 further down the page. Compared to a standard mathematical
158 representation of the usual Cartesian co-ordinate system,
159 it is upside-down.
161 <p><table><tr><td><pre>
163 ========== =================
165 0+-------------+ |
167 | -----+-----
169 | |
171 24+
172 </pre></td></tr></table>
176 <p>The Funge stack stack is a LIFO stack of typical LIFO stacks
177 of cells. In Befunge-93, only two operations
183 to the topmost stack on the stack stack. The push and pop operations
184 are possible on the stack stack as well, but they push and pop entire
185 stacks.
188 (that is, the topmost stack of the stack stack) of cells,
189 completely emptying it.
191 <p>If a program attempts to pop a cell off the stack when it is empty, no
192 error occurs; the program acts as if it popped a 0.
194 <p>In this document, short stacks are generally notated
196 values listed in the documentation are the
198 Long stacks
205 what any given Funge-98 source file name ends in (e.g. you could
208 - "standard" example programs use this suffix.
211 ASCII characters and the end-of-line controls described below.
215 and may have characters greater than 127 present in it (and greater
216 than 255 on systems where characters are stored in multiple bytes;
218 That is to say, character #417 may look like a squiggle on system
219 Foo and a happy face on system Bar, but the meaning is always the
220 same to Funge, 'character #417', regardless of what it looks like.
222 <p>In other words, what Funge characters look like on a particular computer or
223 OS depends entirely on that computer or OS. However, when
224 characters are not generally considered to be printable, they can
225 have special meaning to Funge-98:
227 <ul>
232 </ul>
237 (MS-DOS).
240 should, ideally, be recognized by the interpreter as an end-of-line marker,
242 <ul>
246 </ul>
248 <p>If an interpreter cannot support all three varieties of end-of-line marker,
249 it should be clearly noted in that interpreter's documentation.
252 program is loaded.
256 the source file. There are no such restrictions on Befunge-98 and the
257 user can reasonably expect to be able to have as many lines of as many
258 characters as they want, for non-contrived cases.
261 These default contents are written over by characters in the program
262 source when it is loaded. However, spaces in the program source
263 do not overwrite anything in Funge-Space; in essence the space
264 character is transparent in source files. This becomes important when
267 <p>The source file begins at
271 coordinate to zero. Subsequent lines in Unefunge are simply appended
272 to the first, and the end of the source file indicates the end
273 of the (single) line. End-of-line markers are never copied
274 into Funge-Space.
284 (set of co-ordinates) which represents the "current position" of a running Funge program. It
285 holds the same function as the instruction pointer (or <i>program
286 counter</i> (PC)) in any other language or processor - to indicate
287 where the currently executing instruction is located.
289 <p>In most other languages and machines (both virtual and real,)
290 the IP/PC is restricted to unidirectional travel in a single
291 dimension, with random jumps. However, in Funge, the IP keeps
293 the IP executes its current instruction (that is, the instruction
294 at the location pointed to by the IP), then travels to a new location, by
295 adding its delta vector to its position vector.
298 the IP always begins at the origin and
302 <p>In two dimensions, we have the following terminology.
307 same as how a rook moves in chess and this
308 is in fact the only way the IP can move in Befunge-93.
312 Any moving IP that is not traveling cardinally is said
317 <p>All standard instructions are one character long and range from
319 multicharacter instructions in Funge.
321 <p>An instruction is executed by an IP every tick. The IP
322 executed is the one at the current position of the IP.
323 Only after that does the IP moves by its delta to a new position.
327 assign semantics to these instructions dynamically, allowing
328 the Funge programmer to use libraries of both standard and proprietary
334 <p>For all these reasons, when encountering any unimplemented
336 Unefunge,) the Funge interpreter should at least provide an option
337 for informing the user that it was told to execute an instruction
338 that isn't implemented, and possibly
339 warning the user that this file might be an incorrect language or
340 version.
342 <p>An unimplemented instruction must otherwise act as
344 All undefined or otherwise unimplemented
345 instructions must be considered unimplemented.
351 may be unavailable in different interpreters for many reasons, and
355 the cell it produces.
359 <p>A few instructions are essential for changing the delta of the IP.
362 travel west. These instructions are valid in all Funges.
366 These instructions are not available in Unefunge.
371 in Unefunge or Befunge.
374 a random cardinal direction appropriate to the number of
375 dimensions in use: east or west in Unefunge; north, south,
376 east or west in Befunge, etc.
379 Funge-98.
382 instructions rotate by 90 degrees the delta of the IP which
384 These instructions are not available in Unefunge.
386 <p>To remember which is which, visualize
387 yourself on the seat of a bicycle, looking down at the handlebars:
393 </tr><tr>
397 </tr><tr>
401 </tr></table></center>
404 the IP's delta by -1. In two dimensions, this is
405 the equivalent of reflecting the delta of
406 the IP about the z-axis.
409 the stack, and sets the IP delta to that vector.
411 <p>A vector on the stack is stored bottom-to-top, so that in
419 out of bounds (off the map of Funge-Space) by treating the space
420 as a torus. If the IP leaves the west edge, it reappears on the
421 east edge at the same row; if it leaves the south edge, it
422 reappears at the north edge at the same column, and vice
423 versa in both cases.
425 <p>For various reasons, toroidal wrapping is problematic
426 in Funge-98. Instead, we use a special wrapping technique that
427 has more consistent results in this new, more flexible
428 environment where Funge-Space can have an arbitrary size
431 <p>Same-line wrapping can be described in several ways,
432 but the crucial idea it encompasses is this: unless the delta
433 or position of the IP were to be changed by an intervening instruction,
434 the IP will always wrap such that it would eventually
435 return to the instruction it was on before it wrapped.
437 <p>The mathematical description of same-line wrapping is
439 topological space. It is generally of more interest to
440 topologists and mathematicians than programmers. We won't
441 cover it here, but it is included in the
444 <p>The algorithmic description of same-line wrapping can
446 interest to Funge interpreter implementers than Funge
447 programmers. However, it does describe exactly how the
449 understand, so we will include it here.
451 <p>When the IP attempts to travel into the whitespace
452 between the code and the end of known, addressable space, it backtracks.
453 This means that its delta is reversed and it ignores
454 (skips over without executing) all instructions. Travelling thus, it finds the other 'edge' of
455 code when there is again nothing but whitespace in front of it. It
456 is reflected 180 degrees once more (to restore its original delta)
457 and stops ignoring instructions. Execution then resumes normally
458 - the wrap is complete.
462 <p>It is easy to see at this point that the IP remains on the same
464 ticks in regards to multithreading, as would be expected from any
465 wrapping process.)
467 <p>Same-line wrapping has the advantage of being
468 backward-compatible with Befunge-93's toroidal wrapping. It also works
469 safely both when the IP delta is flying (non-cardinal), and when the
470 size of the program changes.
473 character. (This holds true with most decent Befunge-93 interpreters,
474 too, although it was not in the original.)
478 continues on its merry way.
482 whatsoever", and this becomes important when you have more than one
484 you'll read about later. For an explicit nop instruction in
489 read about later.
494 the next Funge-Space cell in its path.
497 In non-Concurrent Funge, there is only a single IP.
498 Either way, when no IP's are left alive,
499 the program will subsequently end with no error (returning error code 0).
502 in Funge-98.
505 jump over all subsequent
507 takes zero ticks to execute, so that subroutines, comments,
508 and satellite code can be insulated by surrounding it with
512 be truly executed, in the sense of it taking up a tick and
513 doing something.
516 value off the stack, and jumps over that many spaces.
523 ends the entire program immediately
524 (regardless of the number of IPs active in Concurrent Funge).
525 It also pops a cell off the stack and uses that value as
526 the return value of the Funge interpreter to the
527 operating system.
529 <p>Note that most operating systems will only look at
530 the least significant byte your return value, unsigned.
531 But you can return a full cell, and the OS will interpret
532 as much of it as it can handle, treating it as
533 signed or unsigned as the OS demands.
536 off the stack. Then it finds the next instruction
537 in Funge-space in the path of the IP (note that this cannot
540 respect to concurrent operation.
542 <p>Note that some instructions don't make much sense within
544 of the possibilities for how many times the instruction
545 is repeated. For example, no matter how
547 the result is the same.
550 behaviour.
558 the stack and pushes a value which is the logical negation of it.
559 If the value is zero, it pushes one; if it is non-zero, it pushes
560 zero.
563 stack, then pushes a one if second cell is greater than the
564 first. Otherwise pushes a zero.
566 <p>Funge has instructions that act like directional 'if' statements.
573 is not available in Unefunge.
576 instruction pops a value off the
579 or Befunge.
589 delta. This instruction is not available in Befunge-93, nor
590 Unefunge.
597 push the values zero
598 through nine onto the stack, respectively.
600 through 15 respectively.
603 them using integer addition,
604 and pushes the result back onto the stack.
607 from the stack, multiplies them using integer multiplication,
608 and pushes the result back onto the stack. In this way numbers
612 <pre>
615 or
617 <pre>
620 <p>Funge also offers the following arithmetic instructions:
621 <ul>
623 first from the second using integer subtraction, and pushes the result;
625 two values, divides the second by the first using integer division,
626 and pushes the result (note that division by zero produces
629 the division to be); and
631 which pops two values, divides the
632 second by the first using integer division,
633 and pushes the remainder, of those.
634 Remainder by zero is subject to the same rules as division by zero,
635 but if either argument is negative, the result is implementation-defined.
636 </ul>
641 toggles a special mode of the Funge
642 interpreter called <i>stringmode</i>. In stringmode, every cell
644 is not interpreted as an instruction, but rather as a Funge
646 toggles stringmode once more, turning it off.
649 that is, when any contiguous series of spaces is processed,
650 it only takes one tick and pushes one space onto the stack. This
651 introduces a small backward-incompatibility with
652 Befunge-93; programs that have multiple spaces and/or wrap while
653 in stringmode will have to be changed to work the same under
654 Funge-98.
656 <pre>
657 Befunge-93 Befunge-98
663 instruction in Funge-98. This pushes the Funge character value
664 of the next encountered cell (position + delta) onto the stack,
665 then adds the delta to the position (like <code>#</code>), skipping
666 over the character (in no ticks). For example, the
667 following two snippets perform the same function, printing a Q:
671 <p><code>'Q,</code>
674 <code>'</code> instruction: this instead pops a value off
675 the stack and writes it into (position + delta).
677 <p>Some instructions expect a Funge string on the stack as one of
678 their arguments. The standard format for these strings is called
680 start of the string at the top of the stack and the null
681 termination at the bottom.
686 discards it.
689 back onto the stack twice, duplicating it.
692 the first cell back on, then the second cell, in effect swapping the
693 top two cells on the stack.
696 completely wipes the stack (popping and discarding elements
697 until it is empty.)
701 <p>The stack stack transparently overlays
702 the stack - that is to say, the top stack of
703 Funge-98's stack stack is treated the same as
704 Befunge-93's sole stack. The Funge programmer
705 will never notice the difference unless they
706 use the <code>{</code>, <code>}</code>, or <code>u</code>
707 instructions of Funge-98.
709 <p>When working with different stacks on the stack
710 stack, though, it's useful to give two of them
711 names: the <i>top of stack stack</i> or TOSS,
712 which indicates the topmost stack on
713 the stack stack, which works to emulate the
714 sole stack of Befunge-93;
715 and the <i>second on stack stack</i> or
716 SOSS, which is the stack directly under
717 the TOSS.
720 it calls <i>n</i>, then pushes a new stack on the
721 top of the stack stack,
722 transfers <i>n</i>
723 elements from the SOSS to the TOSS,
724 then pushes the storage offset
725 as a vector onto the SOSS,
726 then sets the new storage offset to the location to be
727 executed next by the IP (storage offset <- position + delta).
728 It copies these elements as a block, so order is preserved.
730 <p>If the SOSS contains <i>k</i> elements, where <i>k</i> is less than <i>n</i>, the
731 <i>k</i> elements are transferred as the top <i>k</i> elements and the remaining
732 bottom (<i>n-k</i>) elements are filled in with zero-value cells.
734 <p>If <i>n</i> is zero, no elements are transferred.
736 <p>If <i>n</i> is negative, |<i>n</i>| zeroes are pushed onto the SOSS.
739 the stack that it calls <i>n</i>, then pops a vector off the SOSS which
740 it assigns to the storage offset, then transfers <i>n</i> elements (as a block)
741 from the TOSS to the SOSS, then pops the top stack off the stack stack.
748 <p>If <i>n</i> is zero, no elements are transferred.
750 <p>If <i>n</i> is negative, |<i>n</i>| cells are popped off of the (original) SOSS.
752 <p><code>{</code> makes the current TOSS the new SOSS.
753 <code>}</code> makes the current SOSS the new TOSS.
755 <p><code>{</code> may act like <code>r</code> if no more memory is available for another stack.
756 <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.)
762 <i>count</i> and transfers that many
763 cells from the SOSS to the TOSS.
764 It transfers these cells in a pop-push loop.
765 In other words, the order is not preserved during transfer,
766 it is reversed.
768 <p>If there is no SOSS (the TOSS is the only stack), <code>u</code>
769 should act like <code>r</code>.
771 <p>If <i>count</i> is negative, |<i>count</i>| cells are
772 transferred (similarly in a pop-push loop) from the TOSS to the
773 SOSS.
775 <p>If <i>count</i> is zero, nothing happens.
782 store and retrieve data and code in Funge-Space.
784 <p>In Befunge-93, <code>g</code> pops a vector (that is, it pops a y value,
785 then an x value,) and pushes the value (character)
786 in the Befunge-Space cell
787 at (x, y) onto the stack.
788 <code>p</code> pops a vector, then it pops a value, then it
789 places that value in the Funge-Space cell at (x, y).
791 <p>In Funge-98, each IP has an additional vector property called the
792 <i>storage offset</i>. Initially this vector is the set to the
793 origin. As such, it works to emulate Befunge-93. The arguments
794 to <code>g</code> and <code>p</code> are the same, but instead of pointing
795 to absolute locations in Funge-Space, they reference a cell relative
796 to the storage offset.
802 instructions provide numeric and Funge
803 character/control output, respectively; they pop a cell off the stack
804 and send it in numeric or Funge character format to the <i>standard
805 output</i>, which is usually displayed by the interpreter in an
806 interactive user terminal.
808 <p>Outputting character number 10 will result in a new line being
809 displayed on the standard output.
811 <p>Numeric output is formatted as a decimal integer followed by a space.
813 <p>These instructions will act as <code>r</code> does, should the standard
814 output fail for any reason.
818 instructions provide numeric and Funge
819 character/control input, respectively. They each suspend the
820 program and wait for the user to enter a value in numeric or Funge
821 character format to the <i>standard input</i>, which is usually
822 displayed with the standard output. They then push this value
823 on the stack.
825 <p>An input of character number 10 indicates that the user pressed
826 the 'Enter' key, or the equivalent key on their keyboard.
828 <p>Decimal input reads and discards characters until it encounters
829 decimal digit characters, at which point it reads a decimal
830 number from those digits, up until (but not including)
831 the point at which input characters stop being digits,
832 or the point where the next digit would cause a cell overflow,
833 whichever comes first.
835 <p>Although the standard input and output are generally displayed
836 in some sort of interactive user terminal, they needn't be;
837 many operating systems support <i>redirection</i>. In the
838 case of an end-of-file or other file error condition, the <code>&</code>
839 and <code>~</code> both act like <code>r</code>.
845 are only available in Funge-98.
848 followed by a flags cell, then a
849 vector Va telling it where to operate. If the file can be opened
850 for reading, it is inserted into Funge-Space at Va, and immediately closed.
851 Two vectors are then pushed onto the stack, Va and Vb, suitable arguments to
852 a corresponding <code>o</code> instruction.
853 If the file open failed, the instruction acts like <code>r</code>.
855 <p><code>i</code> is in all respects similar to the procedure used
856 to load the main Funge source code file, except it may specify
857 any file, not necessarily Funge source code,
858 and at any location, not necessarily the origin.
860 <p>Also, if the least significant bit of the flags cell is high,
861 <code>i</code> treats the file as a binary file; that is, EOL and FF
862 sequences are stored in Funge-space instead of causing the
863 dimension counters to be reset and incremented.
865 <p><code>o</code> first pops a
867 Then it pops a flags cell.
868 It then pops a vector Va indicating a <i>least point</i>
869 (point with the smallest numerical coordinates of a region;
870 also known as the upper-left corner, when used in the context
871 of Befunge) in space, and another vector Vb
872 describing the size of a rectangle (or a rectangular prism in
873 Trefunge, etc).
874 If the file named by the filename can be opened
875 for writing, the contents of the rectangle of Funge-Space
876 from Va to Va+Vb are written into it, and it is immediately closed.
877 If not, the instruction acts like <code>r</code>.
879 <p>The first vectors popped by both of these instructions
880 are considered relative to the storage offset.
881 (The size vector Vb, of course, is relative to the least point Va.)
883 <p>Note that in a greater-than-two-dimensional environment,
884 specifying a more-than-two-dimensional size such as (3,3,3)
885 is not guaranteed to produce sensical results.
887 <p>Also, if the least significant bit of the flags cell is high,
888 <code>o</code> treats the file as a linear text file; that is, any spaces
889 before each EOL, and any EOLs before the EOF, are not written
890 out. The resulting text file is identical in appearance and takes
891 up less storage space.
896 pops a string off the stack, and attempts to execute it.
897 How it executes it is implementation dependant.
898 However, an implementation may support one of several
899 standardized ways of interpreting the string,
900 and which routine it uses can be determined by querying <code>y</code>.
901 Typically methods include treating it as a
902 C system() call would, or on a platform such as MacOS,
903 for example, treating the string as AppleScript would be in order.
905 <p>After execution, a failure value is pushed onto the stack.
906 If this value is zero, everything went as expected. If the
907 value is non-zero, it may be the return-code of the program
908 that was executed; at any rate it means that the attempt to
909 execute the program, or the program itself, did not succeed.
914 pops one value off the stack. If the value is zero
915 or negative, <code>y</code> tells you far more than you
916 ever really want to know about the underlying Funge
917 interpreter, operating system, and computer
918 (and is thus usually followed soon after
919 by a <code>n</code> instruction).
921 <p>Each cell of information retrieved by <code>y</code>, only applies to
922 either the current IP, the current environment (that is,
923 the interpreter of the current IP,) or the global environment
924 (the environment of every IP in the same Funge-space, regardless
925 of which interpreter it's running on.)
927 <p>After an execution of <code>y</code> with a non-positive argument,
928 the stack contains many more cells (listed from top to bottom:)
930 <ol>
931 <li>1 cell containing flags (env).
932 <ul>
933 <li>Least Significant Bit 0 (0x01): high if <code>t</code> is implemented. (is this Concurrent Funge-98?)
934 <li>Bit 1 (0x02): high if <code>i</code> is implemented.
935 <li>Bit 2 (0x04): high if <code>o</code> is implemented.
936 <li>Bit 3 (0x08): high if <code>=</code> is implemented.
937 <li>Most Significant Bit 4 (0x10): high if unbuffered standard I/O
938 (like <code>getch()</code>) is in effect, low if the usual
940 <li>Further more significant bits: undefined, should all be low in Funge-98
941 </ul>
942 <li>1 cell containing the number of bytes per cell (global env).
943 <ul>aka cell size. Typically 4, could also be 2, 8, really really large, infinity, etc.
944 </ul>
945 <li>1 cell containing the implementation's handprint (env).
946 <li>1 cell containing the implementation's version number (env).
947 <ul>If the version number contains points,
948 they're stripped. v2.01 == 201, v1.03.05 = 10305, v1.5g = 1507.
949 Don't use non-numbers in the version number to indicate 'personalizations' - change the handprint instead.</ul>
950 <li>1 cell containing an ID code for the Operating Paradigm (global env)
951 <ul>
952 <li>0 = Unavailable
953 <li>1 = Equivalent to C-language system() call behaviour
954 <li>2 = Equivalent to interpretation by a specific shell or program
955 <ul>This shell or program is specified by the interpreter but should ideally be customizable
956 by the interpreter-user, if applicable. Befunge programs that run under this
957 paradigm should document what program they expect to interpret the string
958 passed to <code>=</code>.</ul>
959 <li>3 = Equivalent to interpretation by the same shell as started this Funge interpreter, if applicable
960 <ul>If the interpreter supports this paradigm, then in this manner, the user executing a
961 Befunge source can easily choose which shell to use for <code>=</code> instructions.</ul>
962 </ul>
963 This value is included so the program can have a reasonable idea of what <code>=</code> will do.
964 The values shown here are only the most basic set available at the time of publication.
965 See the <a href="#Registry">Registry</a> for any late-breaking headway into further Operating Paradigms.
966 <li>1 cell containing a path seperator character (global env)
967 <ul>
968 This is what path seperators for <code>i</code> and <code>o</code> filenames should look like.
969 </ul>
970 <li>1 cell containing the number of scalars per vector (global env)
971 <ul>aka number of dimensions. 2 for Befunge, 1 for Unefunge, 3 for Trefunge.</ul>
972 <li>1 cell containing a unique ID for the current IP (ip)
973 <ul>Only significant for Concurrent Funge.
974 This ID differentiates this IP from all others currently in the IP list.</ul>
975 <li>1 cell containing a unique team number for the current IP (ip)
976 <ul>Only significant for NetFunge, BeGlad, and the like.</ul>
977 <li>1 vector containing the Funge-Space position of the current IP (ip)
978 <li>1 vector containing the Funge-Space delta of the current IP (ip)
979 <li>1 vector containing the Funge-Space storage offset of the current IP (ip)
980 <li>1 vector containing the least point which contains a non-space cell, relative to the origin (env)
981 <li>1 vector containing the greatest point which contains a non-space cell, relative to the least point (env)
982 <ul>These two vectors are useful to give to the o instruction to output the entire program source as a text file.</ul>
983 <li>1 cell containing current ((year - 1900) * 256 * 256) + (month * 256) + (day of month) (env)
984 <li>1 cell containing current (hour * 256 * 256) + (minute * 256) + (second) (env)
985 <li>1 cell containing the total number of stacks currently in use by the IP (size of stack stack) (ip)
986 <li><i>size-of-stack-stack</i> cells containing size of each stack, listed from TOSS to BOSS (ip)
987 <ul>Stack sizes are pushed as if they were measured <b>before</b> <code>y</code> began pushing elements onto the stack.</ul>
988 <li>a series of sequences of characters (strings), each terminated by a null, the series terminated by an additional double null, containing the command-line arguments. (env)
989 <ul>This means any isolated argument can be a null string, but no two consecutive arguments
990 may be null strings - a rather contrived scenario, null string arguments being rare in themselves.</ul>
991 <ul>The first string is the name of the Funge source program being run.</ul>
992 <li>a series of strings, each terminated by a null, the series terminated by an additional null, containing the environment variables. (env)
993 <ul>The format for each variable setting is <tt>NAME=VALUE</tt>.</ul>
994 </ol>
996 <p>If <code>y</code> is given a positive argument, all these cells are
997 pushed onto the stack as if the argument was non-positive.
998 However, <code>y</code> then goes on to copy the <i>argument</i>th
999 stack cell (counting from the top) into a temporary location,
1000 subsequently removing all the cells
1001 it pushed onto the stack. It then pushes the temporary cell
1002 onto the stack. For example, <code>3y</code> will act as if only
1003 the handprint was pushed onto the stack.
1005 <p>An interesting side-effect of this behaviour is that if
1006 <code>y</code> is given an argument that exceeds the number of
1007 cells it pushes onto the stack, it can act as a 'pick'
1008 instruction on data that was on the stack before <code>y</code>
1009 was even executed.
1013 <p>Funge-98 is totally customizable and scalable in terms of functionality, and
1014 non-trivial programs can now be written portably in it without any sort of
1015 directives. The fingerprint mechanism allows for the definition of a
1016 virtually unlimited number of libraries in the form of fingerprinted extensions. The
1017 handprint mechanism allows a program to identify exactly what interpreter it's
1018 running on.
1022 <p>A handprint is a bitstring which uniquely identifies
1023 a particular implementation (interpreter, compiler, etc.)
1024 of Funge-98.
1026 <p>These should really only be used by Funge-98 programs which know about <b>bugs</b>
1027 in a known interpreter, and want to work around them when their portable source
1028 is run on that interpreter.
1029 (<i>Features</i>, on the other hand, should be
1030 fingerprints: if everything is properly implemented, the current handprint <b>should</b> be
1031 irrelevant. Fingerprints should always be used in preference to handprints
1032 when making a design decision - handprints are a fallback for the less-than-ideal case.)
1034 <p>Handprints
1035 generally stay they same between revisions of an interpreter. They are
1036 accompanied by a version number when retrieved from <code>y</code>.
1040 <p>Extension and customization of Funge-98 are accomplished
1042 exists for Befunge-93.
1044 <p>To be more precise, a fingerprint is a unique ID code which indicates a library
1045 of routines (a <i>fingerprinted extension</i>) to be assigned temporarily to what the instructions <code>A</code> to <code>Z</code> do.
1046 Multiple loaded fingerprints can overlap and overload, so even
1047 object-oriented-like inheritance is possible.
1049 <p>Generally speaking, these new semantics and instructions are only available
1050 to and only apply to the IP which loaded them. The fingerprint spec itself may
1051 make exceptions to this rule, but it must clearly specify what they are.
1053 <p>The semantics of any given extension are generally
1054 coded directly into the interpreter. There is
1055 no reason, however, they may not be made available in a dynamically-loadable form;
1056 but there is no convenient, standard format for such a form.
1058 <p>Whether the semantics are dynamically loaded from a disk file containing some
1059 form of executable code, or hard-wired into the Funge interpreter, is really a
1060 moot point from the Funge programmer's perspective.
1062 <p>However, it is useful to explain at this point for the benefit of both Funge
1063 programmers and potential Funge extension writers, that there are two classes of
1064 fingerprinted extensions: those that interact with and change the behaviour of the underlying
1065 Funge Virtual Machine and/or are not re-entrant (<i>feral extensions</i>), and
1066 those which are self-contained and re-entrant (<i>tame extensions</i>).
1068 <p>The main difference is that a feral extension cannot simply or easily be "dropped into" a Funge interpreter which is not aware of it. When specifying fingerprinted extensions for public use, please try to make them as tame as possible - although many times it is unavoidable to have a feral fingerprint in order to accomplish a certain semantic goal, such as program control of proprietary interpreter features.
1071 loads the semantics for a given fingerprint
1072 onto any or all of the
1073 instructions <code>A</code> to <code>Z</code>.
1074 <code>(</code> pops a <i>count</i>.
1075 It then pops <i>count</i> cells.
1076 For each cell that it pops, it
1077 multiplies a temporary value
1078 (which is initially zero) by 256,
1079 and adds the cell value to it.
1081 <p>In this way, <code>(</code>
1082 builds a fingerprint. This mechanism makes it
1083 simple to express large fingerprints
1084 like 0x452e472e in printable ASCII
1086 requiring the use of ASCII as the medium for all fingerprints.
1088 <p><code>(</code> then uses this fingerprint to
1089 locate and load a set of semantics for the
1090 instructions <code>A</code> to <code>Z</code>. If the Funge implementation
1091 cannot find the correct library for the given
1092 fingerprint, <code>(</code> acts like <code>r</code>.
1093 If, however, the semantic library load is successful,
1094 the new fingerprint, then a 1, are pushed onto
1095 the stack (to be accepted by a subsequent <code>)</code> instruction.)
1098 unloads the semantics for a given fingerprint
1099 from any or all of the
1100 instructions <code>A</code> to <code>Z</code>
1101 (even if that fingerprint had never been loaded before).
1102 It pops a <i>count</i> and builds a fingerprint in exactly
1103 the same way.
1106 The interpreter-writer or interpreter-customizer is allowed to make
1107 fingerprints do anything they like, and they may implement
1108 fingerprints however they like, but they have to follow some general rules
1109 as a 'contract' between the fingerprint and the fingerprint user.
1111 <ul>
1112 <li>A fingerprint should not affect the semantics of any instructions
1113 besides <code>A</code> to <code>Z</code>, except under exceptional circumstances
1114 which must be clearly documented in the fingerprint's spec.
1115 <li>When loaded, a fingerprint which implements <code>A</code> and <code>B</code>
1116 semantics should act something like:
1118 <ul>save(<code>A</code>); bind(<code>A</code>, myAsemantic()); save(<code>B</code>); bind(<code>B</code>, myBsemantic());</ul>
1120 <li>When unloaded, the same fingerprint should act something like
1122 <ul>restore(<code>B</code>); restore(<code>A</code>);</ul>
1124 <li>In this sense, 'bind' means to change what the execution of an instruction does in the current Funge-98 program.
1125 <li>'save' means to save (push onto a stack) the semantics of an instruction for later use.
1126 <li>'restore' means to recall (pop from a stack) the semantics of an instruction from the last saved version.
1127 </ul>
1129 <p>This allows 'overloading' fingerprints.
1130 Say three fingerprints are implemented on your interpreter,
1132 <ul>
1133 <li><code>E.G.</code> which implements <code>D</code> as 'Destroy' and <code>R</code> as 'Restore'
1134 <li><code>TEST</code> which implements <code>S</code> as 'Send', <code>R</code> as 'Receive', and <code>E</code> as 'Encrypt'
1135 <li><code>WORK</code> which implements <code>S</code> as 'Slice', <code>D</code> as 'Dice', <code>P</code> as 'Puree'
1136 </ul>
1138 <p>With these, the Funge programmer ought to be able to make code like:
1142 <p>Here, the <code>S</code> instruction indicates the 'Slice' instruction in the
1143 WORK fingerprint, not 'Send' in TEST. But if it was written as:
1147 <p>The <code>S</code> would indicate 'Send' from TEST, since there is no <code>S</code> in E.G.,
1148 and a <code>D</code> instruction in the same location would indicate 'Destroy'
1149 in E.G., but <code>P</code> would be a 'Puree' from WORK, because it's not
1150 defined in either TEST or E.G.
1154 <p>The Funge Central Registry is an online database located
1155 at <code><A HREF="http://www.cats-eye.com/funge/registry/">http://www.cats-eye.com/funge/registry/</A></code>.
1156 Before developing and releasing your own Funge-98 implementation
1157 or extension, please register all applicable handprints
1158 and fingerprints you will require here.
1160 <p>This system is in place both to reduce conflicts between fingerprints
1161 and handprints world-wide, ensuring their uniqueness, and to
1162 provide a quick reference to all known extant handprints and
1163 fingerprints.
1165 <p>There really are no standard libraries in Befunge.
1166 A Funge-98 interpreter need not implement any fingerprints whatsoever.
1168 extensions, catalogued in the Registry by their fingerprints. Since
1169 extensions are forever accumulating, see the registry for a list of
1175 <p><code>/</code> modifiers:
1177 <ul>
1178 <li><code>98</code> Funge-98 only, not in Befunge-93.
1179 <li><code>2D</code> Minimum 2 dimensions (not in Unefunge).
1180 <li><code>3D</code> Minimum 3 dimensions (not in Unefunge or Befunge).
1181 <li><code>c</code> Concurrent Funge. Check <code>y</code> to see if these instructions are implemented.
1182 <li><code>f</code> Filesystem Funge. Check <code>y</code> to see if these instructions are implemented.
1183 </ul>
1185 <p><table border=1>
1186 <tr><th rowspan=2>Decimal</th><th rowspan=2>ASCII</th><th rowspan=2>Instruction </th><th>Stack Before</th><th>Stack After</th><th rowspan=2>Other Effects</th></tr>
1187 <tr><td colspan=2 align=center><i>(bottom ... top)</i></td></tr>
1188 <tr><td>32 </td><td>space </td><td>Space </td><td> </td></td><td> </td><td>not normally executed</td></tr>
1189 <tr><td>33 </td><td><code>!</code> </td><td>Logical Not </td><td>b </td><td>NOT b</td><td> </td></tr>
1190 <tr><td>34 </td><td><code>"</code> </td><td>Toggle Stringmode </td><td> </td><td> </td><td>stringmode <- NOT stringmode</td></tr>
1191 <tr><td>35 </td><td><code>#</code> </td><td>Trampoline </td><td> </td><td> </td><td>pos <- pos + delta</td></tr>
1192 <tr><td>36 </td><td><code>$</code> </td><td>Pop </td><td>n </td><td> </td><td> </td></tr>
1193 <tr><td>37 </td><td><code>%</code> </td><td>Remainder </td><td>a b </td><td>a REM b </td><td> </td></tr>
1194 <tr><td>38 </td><td><code>&</code> </td><td>Input Integer </td><td> </td><td>a </td><td>a = readint()</td></tr>
1195 <tr><td>39 </td><td><code>'</code> </td><td>Fetch Character/98 </td><td> </td><td>c </td><td>pos <- pos + delta</td></tr>
1196 <tr><td>40 </td><td><code>(</code> </td><td>Load Semantics/98 </td><td>en..e1 n </td><td>f 1 </td><td>overloads A-Z</td></tr>
1197 <tr><td>41 </td><td><code>)</code> </td><td>Unload Semantics/98 </td><td>en..e1 n </td><td> </td><td>unloads last A-Z</td></tr>
1198 <tr><td>42 </td><td><code>*</code> </td><td>Multiply </td><td>a b </td><td>a * b </td><td> </td></tr>
1199 <tr><td>43 </td><td><code>+</code> </td><td>Add </td><td>a b </td><td>a + b </td><td> </td></tr>
1200 <tr><td>44 </td><td><code>,</code> </td><td>Output Character </td><td>c </td><td> </td><td>writechar(c)</td></tr>
1201 <tr><td>45 </td><td><code>-</code> </td><td>Subtract </td><td>a b </td><td>a - b</td><td> </td></tr>
1202 <tr><td>46 </td><td><code>.</code> </td><td>Output Integer </td><td>a </td><td> </td><td>writeint(a)</td></tr>
1203 <tr><td>47 </td><td><code>/</code> </td><td>Divide </td><td>a b </td><td>a / b</td><td> </td></tr>
1204 <tr><td>48 </td><td><code>0</code> </td><td>Push Zero </td><td> </td><td>0 </td><td> </td></tr>
1205 <tr><td>49 </td><td><code>1</code> </td><td>Push One </td><td> </td><td>1 </td><td> </td></tr>
1206 <tr><td>50 </td><td><code>2</code> </td><td>Push Two </td><td> </td><td>2 </td><td> </td></tr>
1207 <tr><td>51 </td><td><code>3</code> </td><td>Push Three </td><td> </td><td>3 </td><td> </td></tr>
1208 <tr><td>52 </td><td><code>4</code> </td><td>Push Four </td><td> </td><td>4 </td><td> </td></tr>
1209 <tr><td>53 </td><td><code>5</code> </td><td>Push Five </td><td> </td><td>5 </td><td> </td></tr>
1210 <tr><td>54 </td><td><code>6</code> </td><td>Push Six </td><td> </td><td>6 </td><td> </td></tr>
1211 <tr><td>55 </td><td><code>7</code> </td><td>Push Seven </td><td> </td><td>7 </td><td> </td></tr>
1212 <tr><td>56 </td><td><code>8</code> </td><td>Push Eight </td><td> </td><td>8 </td><td> </td></tr>
1213 <tr><td>57 </td><td><code>9</code> </td><td>Push Niner </td><td> </td><td>9 </td><td> </td></tr>
1214 <tr><td>58 </td><td><code>:</code> </td><td>Duplicate </td><td>v </td><td>v v </td><td> </td></tr>
1215 <tr><td>59 </td><td><code>;</code> </td><td>Jump Over/98 </td><td> </td><td> </td><td>nothing executed until next semicolon</td></tr>
1216 <tr><td>60 </td><td><code><</code> </td><td>Go West </td><td> </td><td> </td><td>delta <- (-1,0)</td></tr>
1217 <tr><td>61 </td><td><code>=</code> </td><td>Execute/98/f </td><td>STR </td><td>r</td><td>r = system-execute(STR)</td></tr>
1218 <tr><td>62 </td><td><code>></code> </td><td>Go East </td><td> </td><td> </td><td>delta <- (1,0)</td></tr>
1219 <tr><td>63 </td><td><code>?</code> </td><td>Go Away </td><td> </td><td> </td><td>delta <- (1,0)?(-1,0)?(0,1)?(0,-1)</td></tr>
1220 <tr><td>64 </td><td><code>@</code> </td><td>Stop </td><td> </td><td> </td><td>halt IP</td></tr>
1221 <tr><td>65-90 </td><td><code>A-Z</code> </td><td> </td><td> </td><td> </td><td>Fingerprint-Defined/98</td></tr>
1222 <tr><td>91 </td><td><code>[</code> </td><td>Turn Left/98/2D </td><td> </td><td> </td><td>delta <- rot(-90, delta)</td></tr>
1223 <tr><td>92 </td><td><code>\</code> </td><td>Swap </td><td>a b </td><td>b a </td><td> </td></tr>
1224 <tr><td>93 </td><td><code>]</code> </td><td>Turn Right/98/2D </td><td> </td><td> </td><td>delta <- rot(90, delta)</td></tr>
1225 <tr><td>94 </td><td><code>^</code> </td><td>Go North/2D </td><td> </td><td> </td><td>delta <- (0,-1)</td></tr>
1226 <tr><td>95 </td><td><code>_</code> </td><td>East-West If </td><td> b </td><td> </td><td>delta <- if (b) (-1,0) else (1,0)</td></tr>
1227 <tr><td>96 </td><td><code>`</code> </td><td>Greater Than </td><td> a b </td><td>a > b </td><td>either 1 or 0 </td></tr>
1228 <tr><td>97 </td><td><code>a</code> </td><td>Push Ten/98 </td><td> </td><td>10 </td><td> </td></tr>
1229 <tr><td>98 </td><td><code>b</code> </td><td>Push Eleven/98 </td><td> </td><td>11 </td><td> </td></tr>
1230 <tr><td>99 </td><td><code>c</code> </td><td>Push Twelve/98 </td><td> </td><td>12 </td><td> </td></tr>
1231 <tr><td>100 </td><td><code>d</code> </td><td>Push Thirteen/98 </td><td> </td><td>13 </td><td> </td></tr>
1232 <tr><td>101 </td><td><code>e</code> </td><td>Push Fourteen/98 </td><td> </td><td>14 </td><td> </td></tr>
1233 <tr><td>102 </td><td><code>f</code> </td><td>Push Fifteen/98 </td><td> </td><td>15 </td><td> </td></tr>
1234 <tr><td>103 </td><td><code>g</code> </td><td>Get </td><td>Va </td><td>v </td><td>v = fetch-funge-space(offset+Va)</td></tr>
1235 <tr><td>104 </td><td><code>h</code> </td><td>Go High/98/3D </td><td> </td><td> </td><td>delta <- (0,0,-1)</td></tr>
1236 <tr><td>105 </td><td><code>i</code> </td><td>Input File/98/f </td><td>Va f STR </td><td>Va Vb </td><td>inputs file</td></tr>
1237 <tr><td>106 </td><td><code>j</code> </td><td>Jump Forward/98 </td><td>s </td><td> </td><td>pos <- pos + delta * s</td></tr>
1238 <tr><td>107 </td><td><code>k</code> </td><td>Iterate/98 </td><td>n </td><td> </td><td>execute next instruction now, n times</td></tr>
1239 <tr><td>108 </td><td><code>l</code> </td><td>Go Low/98/3D </td><td> </td><td> </td><td>delta <- (0,0,1)</td></tr>
1240 <tr><td>109 </td><td><code>m</code> </td><td>High-Low If/98/3D </td><td>b </td><td> </td><td>delta <- if (b) (0,0,-1) else (0,0,1)</td></tr>
1241 <tr><td>110 </td><td><code>n</code> </td><td>Clear Stack/98 </td><td>en..e1 </td><td> </td><td> </td></tr>
1242 <tr><td>111 </td><td><code>o</code> </td><td>Output File/98/f </td><td>Va Vb f STR </td><td> </td><td>outputs file</td></tr>
1243 <tr><td>112 </td><td><code>p</code> </td><td>Put </td><td>v Va </td><td> </td><td>store-funge-space(offset+Va,v)</td></tr>
1244 <tr><td>113 </td><td><code>q</code> </td><td>Quit/98 </td><td>r </td><td> </td><td>immediate exit, returncode = r</td></tr>
1245 <tr><td>114 </td><td><code>r</code> </td><td>Reflect/98 </td><td> </td><td> </td><td>delta <- delta * -1</td></tr>
1246 <tr><td>115 </td><td><code>s</code> </td><td>Store Character/98 </td><td>c </td><td> </td><td>store-funge-space(position+delta,v) </td></tr>
1247 <tr><td>116 </td><td><code>t</code> </td><td>Split/98/c </td><td> </td><td> </td><td>Split IP</td></tr>
1248 <tr><td>117 </td><td><code>u</code> </td><td>Stack Under Stack/98 </td><td>n </td><td>(en..e1) </td><td> </td></tr>
1249 <tr><td>118 </td><td><code>v</code> </td><td>Go South/2D </td><td> </td><td> </td><td>delta <- (0,1)</td></tr>
1250 <tr><td>119 </td><td><code>w</code> </td><td>Compare/98/2D </td><td>a b </td><td> </td><td>if (a>b) ']' elsif (a<b) '[' else 'z'</td></tr>
1251 <tr><td>120 </td><td><code>x</code> </td><td>Absolute Delta/98 </td><td>Va </td><td> </td><td>delta <- Va</td></tr>
1252 <tr><td>121 </td><td><code>y</code> </td><td>Get SysInfo/98 </td><td>c </td><td>en(..e1) </td><td> </td></tr>
1253 <tr><td>122 </td><td><code>z</code> </td><td>No Operation/98 </td><td> </td><td> </td><td> </td></tr>
1254 <tr><td>123 </td><td><code>{</code> </td><td>Begin Block/98 </td><td>en..e1 n </td><td>(en..e1) </td><td>offset <- pos + delta, etc</td></tr>
1255 <tr><td>124 </td><td><code>|</code> </td><td>North-South If/2D </td><td>b </td><td> </td><td>delta <- if (b) (0,-1) else (0,1)</td></tr>
1256 <tr><td>125 </td><td><code>}</code> </td><td>End Block/98 </td><td>en..e1 n </td><td>(en..e1) </td><td>offset <- SOSS Va, etc</td></tr>
1257 <tr><td>126 </td><td><code>~</code> </td><td>Input Character </td><td> </td><td>c </td><td>c = readchar()</td></tr>
1258 </table>
1264 defines a list of any number of
1265 concurrently running instruction pointers called the
1268 location, delta, and stack.
1273 IP list is processed: instructions encountered by each IP are dealt with
1274 in the sequence the IPs appear on the list, and each IP then moves
1275 as specified by its delta.
1277 <p>The list is always processed repetitively, sequentially, and in the same
1278 direction, and when IP's are deleted they fall out and the next one which
1279 would normally execute anyway actually executes.
1282 available in Concurrent Funge-98 only. It
1283 causes the current IP to be duplicated, and this duplicate is added to the
1285 the parent IP is next executed.
1287 <p>When a child IP is borne unto Funge-Space thus, its location, storage
1288 offset, and stack are all copied verbatim from the parent IP's. The child
1292 If the current IP is the only active IP in the IP list,
1293 the program ends. If it
1294 was not the last in the IP list, there would then be a gap in
1295 the list: in this case the top part of the list "shifts down" and the
1296 next thread in the list is executed.
1302 <p>The requirements for a line in Lahey-space are the following:
1303 Starting from the origin,
1304 no matter what direction you head, you eventually reach the origin.
1305 If you go the other way you reach the origin from the other direction.
1307 <p>We surmise that if you head out on a Lahey-line, you would eventually
1308 return along the same Lahey-line, heading in the same direction,
1309 but coming from the other direction.
1310 This would mean you would eventually repeat your path, and (in Funge terms)
1311 have consistant wrapping through unlimited space.
1313 <p>Now, imagine a sphere of radius one centered one unit above the origin.
1314 Imagine a plane placed two units above the origin, i.e. resting on top of the sphere.
1316 <p><center><img src="laheys.jpg" alt="(laheys.jpg - Chris Hall's POVRay rendering of Lahey-Space)"></center>
1318 <p>One thing you might notice is that when you draw a straight line from the
1319 origin to any point on the plane, you intersect the sphere
1320 exactly twice, once at the origin, once in a unique location.
1321 In this manner, you can map the plane uniquely onto the sphere.
1323 <p>Now, each normal line from a point A on the plane to a point B on the plane can be
1324 transformed into a Lahey-line, which in our model is represented as an arc
1325 of the sphere containing both point A' on the sphere and point B' on the sphere.
1326 This arc can then be extended into a full circle, going 'around' the sphere to wrap.<P>
1330 <p>As mentioned, Funge is a family of programming languages, and Befunge has many relatives and descendants. This document only covers Cartesian Funges. Other Funges, such as Honefunges (hex-net topology) and Kleinefunges (Klein-bottles) are certainly possible.
1332 <p>However, Advanced Funges may not find either torodial space <i>or</i> Lahey-space sufficient
1333 for complex topologies, so this spec provides a language for
1334 defining wrapping behaviour in a mathematical way.
1337 along the lines of:
1341 for Befunge-93. Complex topologies can define their own
1342 wrapping functions. If these functions are strictly and clearly specified in the documentation of the Advanced Funge in question, it will save a lot of confusion to users, and is highly recommended.
1344 <hr>
1348 for license information.
1350 </body>
1351 </html>